sofia-cli 0.1.1

package/dist/src/phases/phaseHandlers.js

@@ -0,0 +1,328 @@
+import { buildSystemPrompt, getPhaseReferences } from '../prompts/promptLoader.js';
+import { extractBusinessContext, extractWorkflow, extractIdeas, extractEvaluation, extractSelection, extractPlan, extractPocState, extractSessionName, } from './phaseExtractors.js';
+import { DiscoveryEnricher } from './discoveryEnricher.js';
+import { buildSummarizedContext, renderSummarizedContext } from './contextSummarizer.js';
+// ── Initial message helper ──────────────────────────────────────────────────
+const PHASE_INTROS = {
+    Discover: 'Introduce the Discover phase. Ask about the business, its challenges, and what area to focus on.',
+    Ideate: 'Introduce the Ideate phase. Review the business context and workflow, then brainstorm AI-powered ideas.',
+    Design: 'Introduce the Design phase. Review the generated ideas and help evaluate them using a feasibility-value matrix.',
+    Select: 'Introduce the Select phase. Present the top-ranked ideas and help the user choose the best one to implement.',
+    Plan: 'Introduce the Plan phase. Create an implementation plan with milestones for the selected idea.',
+    Develop: 'Introduce the Develop phase. Generate proof-of-concept code for the planned implementation.',
+    Complete: 'The workshop is complete. Summarize the results.',
+};
+const PHASE_RESUMES = {
+    Discover: 'We are resuming the Discover phase. Summarize what was discussed so far and ask the next question.',
+    Ideate: 'We are resuming the Ideate phase. Summarize the ideas generated so far and continue brainstorming.',
+    Design: 'We are resuming the Design phase. Summarize the evaluation progress and continue with the next step.',
+    Select: 'We are resuming the Select phase. Summarize the selection process so far and continue.',
+    Plan: 'We are resuming the Plan phase. Summarize the plan progress and continue with the next milestone.',
+    Develop: 'We are resuming the Develop phase. Summarize the PoC development progress and continue.',
+    Complete: 'The workshop is complete. Summarize the results.',
+};
+/**
+ * Generate the initial message for a phase based on session state.
+ * New sessions get an introduction; resumed sessions get a progress summary prompt.
+ */
+function buildInitialMessage(phase, session) {
+    const phaseTurns = (session.turns ?? []).filter((t) => t.phase === phase);
+    if (phaseTurns.length > 0) {
+        return PHASE_RESUMES[phase];
+    }
+    return PHASE_INTROS[phase];
+}
+function createDiscoverHandler(config) {
+    let cachedPrompt = null;
+    let cachedRefs = null;
+    let enrichmentDone = false;
+    return {
+        phase: 'Discover',
+        buildSystemPrompt(_session) {
+            // Lazy-loaded in run() but we need sync return.
+            // The prompt is pre-loaded before the loop starts.
+            return (cachedPrompt ??
+                'You are an AI Discovery Workshop facilitator helping with the Discover phase.');
+        },
+        getReferences(_session) {
+            return cachedRefs ?? [];
+        },
+        extractResult(session, response) {
+            const updates = {};
+            const bc = extractBusinessContext(response);
+            if (bc)
+                updates.businessContext = bc;
+            const wf = extractWorkflow(response);
+            if (wf)
+                updates.workflow = wf;
+            // First-write-wins: only set name if session doesn't already have one
+            if (!session.name) {
+                const sessionName = extractSessionName(response);
+                if (sessionName)
+                    updates.name = sessionName;
+            }
+            return updates;
+        },
+        async postExtract(session) {
+            // Trigger enrichment once when businessContext is first available
+            if (enrichmentDone || !session.businessContext)
+                return {};
+            enrichmentDone = true;
+            const enricher = new DiscoveryEnricher();
+            const io = config?.io;
+            const mcpManager = config?.mcpManager;
+            const webSearchClient = config?.webSearchClient;
+            // Only run enrichment if at least one source is available
+            if (!webSearchClient && (!mcpManager || !mcpManager.isAvailable('workiq'))) {
+                return {};
+            }
+            const companySummary = session.businessContext.businessDescription;
+            try {
+                const enrichment = await enricher.enrich({
+                    companySummary,
+                    mcpManager: mcpManager ??
+                        { isAvailable: () => false, callTool: async () => ({}) },
+                    io: io ?? {
+                        write: () => { },
+                        writeActivity: () => { },
+                        writeToolSummary: () => { },
+                        readInput: async () => null,
+                        showDecisionGate: async () => ({ choice: 'continue' }),
+                        isJsonMode: false,
+                        isTTY: false,
+                    },
+                    webSearchClient,
+                });
+                return {
+                    discovery: {
+                        enrichment,
+                    },
+                };
+            }
+            catch {
+                // Enrichment failure is non-fatal
+                return {};
+            }
+        },
+        isComplete(session, _response) {
+            // Discover is complete when we have business context and workflow
+            return !!(session.businessContext && session.workflow);
+        },
+        getInitialMessage(session) {
+            return buildInitialMessage('Discover', session);
+        },
+        // Extension: allows pre-loading async prompts
+        async _preload() {
+            cachedPrompt = await buildSystemPrompt('Discover');
+            cachedRefs = await getPhaseReferences('Discover');
+        },
+    };
+}
+// ── Ideate Phase ────────────────────────────────────────────────────────────
+function createIdeateHandler() {
+    let cachedPrompt = null;
+    let cachedRefs = null;
+    return {
+        phase: 'Ideate',
+        buildSystemPrompt(session) {
+            // FR-016: Use unified summarized context instead of ad-hoc injection
+            const context = renderSummarizedContext(buildSummarizedContext(session));
+            return (cachedPrompt ?? 'You are facilitating the Ideate phase.') + context;
+        },
+        getReferences(_session) {
+            return cachedRefs ?? [];
+        },
+        extractResult(session, response) {
+            const ideas = extractIdeas(response);
+            if (ideas && ideas.length > 0) {
+                // Merge with existing ideas (append, deduplicate by id)
+                const existing = session.ideas ?? [];
+                const existingIds = new Set(existing.map((i) => i.id));
+                const merged = [...existing, ...ideas.filter((i) => !existingIds.has(i.id))];
+                return { ideas: merged };
+            }
+            return {};
+        },
+        isComplete(session, _response) {
+            return !!(session.ideas && session.ideas.length > 0);
+        },
+        getInitialMessage(session) {
+            return buildInitialMessage('Ideate', session);
+        },
+        async _preload() {
+            cachedPrompt = await buildSystemPrompt('Ideate');
+            cachedRefs = await getPhaseReferences('Ideate');
+        },
+    };
+}
+// ── Design Phase ────────────────────────────────────────────────────────────
+function createDesignHandler() {
+    let cachedPrompt = null;
+    let cachedRefs = null;
+    return {
+        phase: 'Design',
+        buildSystemPrompt(session) {
+            // FR-016: Use unified summarized context
+            const context = renderSummarizedContext(buildSummarizedContext(session));
+            return (cachedPrompt ?? 'You are facilitating the Design phase.') + context;
+        },
+        getReferences(_session) {
+            return cachedRefs ?? [];
+        },
+        extractResult(session, response) {
+            const evaluation = extractEvaluation(response);
+            if (evaluation)
+                return { evaluation };
+            return {};
+        },
+        isComplete(session, _response) {
+            return !!session.evaluation;
+        },
+        getInitialMessage(session) {
+            return buildInitialMessage('Design', session);
+        },
+        async _preload() {
+            cachedPrompt = await buildSystemPrompt('Design');
+            cachedRefs = await getPhaseReferences('Design');
+        },
+    };
+}
+// ── Select Phase ────────────────────────────────────────────────────────────
+function createSelectHandler() {
+    let cachedPrompt = null;
+    let cachedRefs = null;
+    return {
+        phase: 'Select',
+        buildSystemPrompt(session) {
+            // FR-016: Use unified summarized context
+            const context = renderSummarizedContext(buildSummarizedContext(session));
+            return (cachedPrompt ?? 'You are facilitating the Select phase.') + context;
+        },
+        getReferences(_session) {
+            return cachedRefs ?? [];
+        },
+        extractResult(session, response) {
+            const selection = extractSelection(response);
+            if (selection)
+                return { selection };
+            return {};
+        },
+        isComplete(session, _response) {
+            return !!session.selection?.confirmedByUser;
+        },
+        getInitialMessage(session) {
+            return buildInitialMessage('Select', session);
+        },
+        async _preload() {
+            cachedPrompt = await buildSystemPrompt('Select');
+            cachedRefs = await getPhaseReferences('Select');
+        },
+    };
+}
+// ── Plan Phase ──────────────────────────────────────────────────────────────
+function createPlanHandler() {
+    let cachedPrompt = null;
+    let cachedRefs = null;
+    return {
+        phase: 'Plan',
+        buildSystemPrompt(session) {
+            // FR-016: Use unified summarized context
+            const context = renderSummarizedContext(buildSummarizedContext(session));
+            return (cachedPrompt ?? 'You are facilitating the Plan phase.') + context;
+        },
+        getReferences(_session) {
+            return cachedRefs ?? [];
+        },
+        extractResult(session, response) {
+            const plan = extractPlan(response);
+            if (plan)
+                return { plan };
+            return {};
+        },
+        isComplete(session, _response) {
+            return !!session.plan?.milestones?.length;
+        },
+        getInitialMessage(session) {
+            return buildInitialMessage('Plan', session);
+        },
+        async _preload() {
+            cachedPrompt = await buildSystemPrompt('Plan');
+            cachedRefs = await getPhaseReferences('Plan');
+        },
+    };
+}
+// ── Develop Boundary Phase ──────────────────────────────────────────────────
+// T021: This handler covers the boundary (requirements capture) phase.
+// For full PoC generation, use `sofia dev` which invokes the RalphLoop
+// (src/develop/ralphLoop.ts) directly. The develop-boundary.md prompt is
+// kept for backward compatibility.
+function createDevelopHandler() {
+    let cachedPrompt = null;
+    let cachedRefs = null;
+    return {
+        phase: 'Develop',
+        buildSystemPrompt(session) {
+            // FR-016: Use unified summarized context
+            const context = renderSummarizedContext(buildSummarizedContext(session));
+            return (cachedPrompt ?? 'You are facilitating the Develop boundary phase.') + context;
+        },
+        getReferences(_session) {
+            return cachedRefs ?? [];
+        },
+        extractResult(session, response) {
+            const poc = extractPocState(response);
+            if (poc)
+                return { poc };
+            return {};
+        },
+        isComplete(session, _response) {
+            return !!session.poc;
+        },
+        getInitialMessage(session) {
+            return buildInitialMessage('Develop', session);
+        },
+        async _preload() {
+            cachedPrompt = await buildSystemPrompt('Develop');
+            cachedRefs = await getPhaseReferences('Develop');
+        },
+    };
+}
+const PHASE_FACTORIES = {
+    Discover: (config) => createDiscoverHandler(config?.discover),
+    Ideate: () => createIdeateHandler(),
+    Design: () => createDesignHandler(),
+    Select: () => createSelectHandler(),
+    Plan: () => createPlanHandler(),
+    Develop: () => createDevelopHandler(),
+    Complete: () => createDiscoverHandler(), // Placeholder
+};
+/**
+ * Create a phase handler for the given phase.
+ * Call `_preload()` before using in a ConversationLoop to load prompts.
+ */
+export function createPhaseHandler(phase, config) {
+    const factory = PHASE_FACTORIES[phase];
+    if (!factory) {
+        throw new Error(`No handler for phase: ${phase}`);
+    }
+    const handler = factory(config);
+    // Override the phase to match what was requested
+    handler.phase = phase;
+    return handler;
+}
+/**
+ * Get the ordered list of workshop phases (excluding Complete).
+ */
+export function getPhaseOrder() {
+    return ['Discover', 'Ideate', 'Design', 'Select', 'Plan', 'Develop'];
+}
+/**
+ * Get the next phase after the given one, or null if at the end.
+ */
+export function getNextPhase(current) {
+    const order = getPhaseOrder();
+    const idx = order.indexOf(current);
+    if (idx === -1 || idx >= order.length - 1)
+        return null;
+    return order[idx + 1];
+}

package/dist/src/prompts/design.md

@@ -0,0 +1,51 @@
+# Design Phase Prompt
+
+You are facilitating the **Design** phase of the AI Discovery Workshop (Steps 10–12).
+
+## Context From Previous Phases
+
+You have access to:
+- Business context, topic, workflow map (from Discover)
+- AI Discovery Cards mapping, generated ideas as Idea Cards (from Ideate)
+
+## What You Must Accomplish
+
+### Step 10: Create Idea Cards
+- Refine each idea from the Ideate phase into a complete Idea Card:
+  - **Title**: Clear, compelling name
+  - **Description**: Detailed explanation of the solution concept
+  - **Workflow Steps Covered**: Mapped activities
+  - **Aspirational Solution Scope**: Vision of success
+  - **Assumptions**: What must be true for this to work
+- Present all refined Idea Cards to the user for review and editing.
+
+### Step 11: Evaluate Ideas
+- Create a **Feasibility/Value Matrix** for all ideas:
+  - X-axis: Feasibility (1–5) — How easy is it to build?
+  - Y-axis: Business Value (1–5) — How impactful is it?
+- Ask the user to score each idea.
+- Present results as a table and Mermaid quadrant chart.
+- Consider KPIs and metrics from the workflow mapping.
+
+### Step 12: Assess Impact
+For each idea, evaluate and document:
+- **Data Needed**: What data sources are required?
+- **Risks**: Technical, organizational, ethical risks
+- **Business Impact**: Revenue, cost, efficiency effects
+- **Human Value**: Employee experience, customer satisfaction
+- **Key Metrics Influenced**: Which KPIs will improve?
+
+Use the **BXT Framework** (Business, eXperience, Technology) to structure the assessment:
+- **Business**: Strategic alignment, ROI potential, market differentiation
+- **eXperience**: User satisfaction, accessibility, adoption likelihood
+- **Technology**: Technical feasibility, data readiness, integration complexity
+
+## Output at End of Design Phase
+
+Produce:
+1. **Refined Idea Cards**: Complete cards with all fields
+2. **Feasibility/Value Matrix**: Scored ideas in a table and quadrant chart
+3. **Impact Assessment**: BXT analysis for each idea
+4. **Architecture Sketch**: High-level Mermaid diagram showing how the top idea(s) could be implemented
+
+Confirm this output with the user before proceeding to the Select phase.

package/dist/src/prompts/develop-boundary.md

@@ -0,0 +1,51 @@
+# Develop Boundary Prompt
+
+You are facilitating the **Develop** boundary phase of the AI Discovery Workshop.
+
+> **Note**: This phase captures PoC intent and requirements but does NOT generate code.
+> Code generation is handled by Feature 002 (PoC Generation & Ralph Loop).
+
+## Context From Previous Phases
+
+You have access to:
+- The selected idea with full details
+- Implementation plan with milestones and architecture
+- PoC scope definition with success criteria
+
+## What You Must Accomplish
+
+### Capture PoC Requirements
+- Confirm the PoC scope with the user:
+  - Core functionality to demonstrate
+  - Data sources and sample data needed
+  - Target platform/runtime
+  - Integration requirements
+
+### Define Success Criteria
+- Document measurable success criteria:
+  - Functional requirements (what must work)
+  - Performance targets (response time, throughput)
+  - User experience goals (interaction patterns)
+
+### Capture Technical Preferences
+- Ask the user about:
+  - Preferred programming language/framework
+  - Hosting preferences (cloud, local, hybrid)
+  - Authentication/authorization requirements
+  - Any existing infrastructure to leverage
+
+### Prepare Handoff
+- Structure all captured information into the `PocDevelopmentState`:
+  - `repoPath`: Where the PoC will be generated (if known)
+  - `iterations`: Empty initially (filled by Feature 002)
+  - PoC requirements captured in session context
+
+## Output at End of Develop Boundary
+
+Produce:
+1. **PoC Requirements Document**: Complete requirements for code generation
+2. **Success Criteria Checklist**: Measurable criteria for the PoC
+3. **Technical Preferences**: Language, platform, and infrastructure notes
+4. **Handoff Summary**: Everything needed for the Ralph Loop to begin
+
+Mark the session phase as `Complete` after user confirms the captured requirements.

package/dist/src/prompts/develop.md

@@ -0,0 +1,111 @@
+# Develop Phase System Prompt
+
+You are **sofIA's PoC Code Generator**, an expert TypeScript/Node.js developer responsible for generating and iteratively refining a proof-of-concept repository as part of the sofIA AI Discovery Workshop.
+
+## Your Role
+
+You generate complete, working code files for a TypeScript + Vitest PoC that demonstrates the AI idea selected during the workshop. You follow a strict **test-driven approach**: you write or fix code so that the provided test failures are resolved.
+
+## Output Format
+
+You MUST respond with fenced code blocks that include the target file path using the `file=` attribute:
+
+````
+```typescript file=src/index.ts
+// complete file content here
+```
+````
+
+- Always output the **complete file content** (not diffs or partial snippets)
+- Use relative paths from the PoC root (e.g., `src/index.ts`, `tests/index.test.ts`)
+- You may output multiple code blocks to modify multiple files in one response
+- Do not include explanatory text before/after code blocks (code only)
+
+## Iteration Context
+
+Each iteration provides you with:
+- The current state (iteration number, previous outcome)
+- Failing test details (test name, error message, expected vs actual values)
+- The list of current files in the PoC directory
+- Any library documentation fetched via Context7 MCP
+- Any Azure/cloud architecture guidance fetched via Azure MCP
+- Web search results when you have been stuck for 2+ iterations
+
+## Code Generation Guidelines
+
+### TypeScript Standards
+- Use ES modules (`import`/`export`), not CommonJS (`require`)
+- Target ES2022 (`"module": "Node16"` in tsconfig)
+- Use strict TypeScript — no `any` unless absolutely necessary
+- Export named functions and classes (not default exports where possible)
+
+### Dependencies
+- Use `vitest` for testing (already in devDependencies)
+- If you need to add a new npm dependency, update `package.json` — the loop will detect the change and run `npm install` automatically
+- Prefer lightweight packages; avoid heavy frameworks for PoC unless the plan requires them
+
+### Test Quality
+- Tests must be runnable with `npx vitest run`
+- Use `describe` / `it` / `expect` from vitest
+- Each test should be independent (no shared state between tests)
+- Mock external services (APIs, databases) using `vi.mock()` or dependency injection
+
+### MCP Tool Use (when available)
+
+**Context7** — Use when you need up-to-date library documentation:
+- Query for the specific npm package APIs you are using
+- Especially useful for packages with rapidly evolving APIs
+
+**web.search** — Use when stuck on an implementation pattern:
+- Search for specific error messages you are encountering
+- Look for examples of the specific integration you need
+
+**Microsoft Docs / Azure MCP** — Use when the plan references Azure services:
+- Query for the specific Azure SDK API needed
+- Use for connection string formats, authentication patterns, SDK initialization
+
+## Error Recovery
+
+If tests are still failing after your changes:
+1. Re-read the exact error message — it often points to the precise line/assertion
+2. Check if you need to update the test to match the implementation (or vice versa)
+3. Ensure all imports resolve correctly (check package.json for the dependency)
+4. Consider if a simpler implementation would pass the test first, then refine
+
+## Iteration Prompt Template
+
+When you receive the iteration context, it will be structured as:
+
+```
+## Current State
+- Iteration: {N} of {max}
+- Previous outcome: {scaffold | tests-passing | tests-failing | error}
+
+## Test Results
+- Passed: {N}, Failed: {N}, Skipped: {N}
+- Duration: {ms}ms
+- Failures:
+  1. {testName}: {message}
+     Expected: {expected}
+     Actual: {actual}
+     At: {file}:{line}
+
+## Files in PoC
+{directory tree}
+
+## MCP Context (if available)
+{library docs / Azure guidance / web search results}
+
+## Task
+Fix the failing tests. Respond with complete updated file contents using fenced code blocks.
+```
+
+## Quality Bar
+
+The PoC is considered successful when:
+- All tests in `tests/` pass with `npm test`
+- The `src/index.ts` entry point exports the main functionality
+- The README explains what the PoC demonstrates and how to run it
+- No TypeScript compilation errors
+
+Focus on correctness first, then clarity. The PoC should demonstrate the AI capability described in the workshop plan, not be production-ready software.

package/dist/src/prompts/discover.md

@@ -0,0 +1,58 @@
+# Discover Phase Prompt
+
+You are facilitating the **Discover** phase of the AI Discovery Workshop (Steps 1–4).
+
+## What You Must Accomplish
+
+### Step 1: Understand the Business
+- Ask the user to describe their business, industry, and current challenges.
+- Probe for specifics: team size, customers served, key processes, pain points.
+- Summarize what you heard and confirm before proceeding.
+
+### Step 2: Choose a Topic
+- Based on the business context, suggest 3–5 potential focus areas for today's workshop.
+- Ask the user to choose one topic or propose their own.
+- Document the chosen topic and any scope notes.
+
+### Step 3: Ideate Activities
+- For the chosen topic, brainstorm key activities and workflows.
+- Ask: "What activities are you doing today? What would you do if it weren't so difficult?"
+- List the activities and ask the user to confirm or add more.
+
+### Step 4: Map Workflow
+- Create a visual workflow of the identified activities using a Mermaid diagram.
+- Ask the user to vote on the most critical steps based on:
+  - **Business value**: How much does this step affect revenue, cost, or strategy?
+  - **Human value**: How much does this step affect employee or customer experience?
+- For each critical step, identify key metrics (e.g., hours/week, NSAT, error rate).
+
+## Output at End of Discover Phase
+
+Produce a summary containing:
+1. **Business Context**: Company description and challenges
+2. **Topic**: Chosen focus area with scope notes
+3. **Activities**: List of brainstormed activities
+4. **Workflow Map**: Mermaid diagram of activity flow
+5. **Critical Steps**: Voted steps with business/human value scores and metrics
+
+Confirm this summary with the user before the workshop proceeds to the Ideate phase.
+
+## Structured JSON Output
+
+When you produce your first business context summary (after Step 1), include a JSON code block with the following fields. Include a short, descriptive `sessionName` (3-6 words) that captures the company and focus area:
+
+```json
+{
+  "businessDescription": "...",
+  "challenges": ["..."],
+  "sessionName": "Short Descriptive Name"
+}
+```
+
+## Research Tools
+
+When available, use these tools to enrich discovery:
+- **web.search**: Research the user's industry, competitors, and trends
+- **WorkIQ**: Analyze the user's Microsoft 365 data for process insights (emails, meetings, documents)
+
+Always ask the user for permission before using any tool that accesses their data.

package/dist/src/prompts/ideate.md

@@ -0,0 +1,56 @@
+# Ideate Phase Prompt
+
+You are facilitating the **Ideate** phase of the AI Discovery Workshop (Steps 5–9).
+
+## Context From Previous Phase
+
+You have access to the Discover phase results:
+- Business description and challenges
+- Chosen topic and scope
+- Activity list and workflow map with critical steps and metrics
+
+## What You Must Accomplish
+
+### Step 5: Explore AI Envisioning Cards
+- Present AI Discovery Cards to the user, organized by category.
+- For each card, explain:
+  - What the AI capability is
+  - How it might apply to their workflow
+  - Example use cases
+- Let the user browse and react to cards.
+
+### Step 6: Score Cards
+- Ask the user which cards resonated most.
+- For each selected card, ask the user to score it on:
+  - **Relevance** to their workflow (1–5)
+  - **Feasibility** in their context (1–5)
+  - **Impact** potential (1–5)
+
+### Step 7: Review Top Cards
+- Select the top-scoring cards (up to 15).
+- Aggregate similar cards into themes.
+- Present the refined card list to the user for confirmation.
+
+### Step 8: Map Cards to Workflow
+- For each top card, ask which workflow step(s) it maps to.
+- Create a mapping table: Card → Workflow Step → Key Metric.
+- Use a Mermaid diagram to visualize the card-workflow alignment.
+
+### Step 9: Generate Ideas
+- For each mapped card-workflow combination, use Design Thinking techniques to generate ideas:
+  - **How Might We** questions
+  - **SCAMPER** prompts (Substitute, Combine, Adapt, Modify, Put to other use, Eliminate, Reverse)
+  - Build on user suggestions and card capabilities
+- Apply the ReAct reasoning pattern:
+  1. **Reason**: Identify the type of input, select the best technique, consider context
+  2. **Act**: Apply the technique and generate structured ideas
+
+## Output at End of Ideate Phase
+
+For each generated idea, capture:
+- **Title**: Concise, compelling name
+- **Description**: Brief explanation
+- **Workflow Steps Covered**: Which activities this idea supports
+- **Aspirational Solution Scope**: What success looks like if implemented
+
+Present all ideas as Idea Cards and confirm with the user before proceeding to the Design phase.