@contextium/cli 1.6.4 → 1.6.6

package/dist/lib/instructions.js

@@ -0,0 +1,138 @@
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * Shared, operator-agnostic Contextium instructions.
+ *
+ * This is the single source for the *product-behaviour* layer that every AI
+ * operator (Claude Code, Cursor, Codex, Copilot, …) should receive so they all
+ * use Contextium the same way: the Task Awareness protocol and the Workflow
+ * Engineering standard. It deliberately excludes repo-specific dev guidance
+ * (build commands, file-structure, MCP-server code conventions) — those live in
+ * this monorepo's CLAUDE.md and are not part of the shipped experience.
+ *
+ * Each setup-* command writes this block into whatever instruction file the
+ * target operator reads natively (Cursor → .cursor/rules, Codex → AGENTS.md,
+ * Copilot → .github/copilot-instructions.md, …). The content is identical; only
+ * the destination path and wrapper differ.
+ */
+export const INSTRUCTIONS_START = '<!-- contextium-instructions:start -->';
+export const INSTRUCTIONS_END = '<!-- contextium-instructions:end -->';
+/**
+ * The portable product-behaviour instructions. Phrased operator-neutrally
+ * ("your AI assistant", "the agent") and references only the Contextium MCP
+ * tools, which are identical across every operator.
+ */
+export const CONTEXTIUM_INSTRUCTIONS = `## Contextium
+
+Contextium gives your AI assistant shared project context — workflows, context
+libraries, agents, skills, and tasks — through the Contextium MCP tools. Use
+the MCP tools (not guesswork) to load context, track tasks, and drive feature
+work. All tools are prefixed \`mcp__contextium__\` (or exposed by the connected
+Contextium server).
+
+### Task Awareness — AI Agent Protocol
+
+When a workflow is loaded (via the \`load_workflow\` MCP tool), the response
+includes an active task list. Use it to guide session planning:
+
+1. **Present tasks as a clean numbered list** — show only task titles, no status
+   prefixes (\`[TODO]\`, \`[IN PROGRESS]\`) and no IDs in user-facing output. Keep
+   IDs internally for status updates.
+2. **Ask about the project plan** — after listing tasks, ask: "Would you like to
+   add these to a project plan as phases? If no project plan document exists in
+   this workflow, I can create one — or we can tackle them manually."
+3. **Resume in-progress tasks first** — if any task is \`in_progress\`, pick it up
+   before starting new work.
+4. **Pick the highest-priority pending task** — if nothing is in progress, take
+   the first \`not_started\` task from the list.
+5. **Mark tasks in-progress** — call \`update_task_status(taskId, 'in_progress')\`
+   when starting a task.
+6. **Mark tasks done** — call \`update_task_status(taskId, 'done')\` when finishing.
+7. **Add newly discovered tasks** — call \`add_task(workflowId, title)\` for work
+   items identified during the session.
+8. **One task at a time** — do not start a new task until the current one is done
+   or explicitly blocked.
+
+MCP tools: \`add_task\`, \`update_task_status\`, \`list_tasks\`.
+
+### Workflow Engineering — Development Standard
+
+All new Contextium feature development uses the workflow engineering framework:
+
+- Every new feature starts with a workflow created in the Contextium workspace.
+- The Planner agent runs once to write the spec and full phase list as
+  individual tagged files in the project library.
+- The Builder implements one phase per session — hard rule, no exceptions.
+- The Reviewer independently grades each implementation before it is marked
+  complete.
+- Never start writing code for a new feature without a workflow and phase list
+  in place.
+
+**Project MCP tools:**
+- \`list_phases(workflowId)\` — returns the pending phases (use the first).
+- \`update_phase_status(phaseId, "done")\` — marks a phase complete after review.
+- \`load_workflow(workflowId)\` — loads full project state for session onboarding.
+
+**Agent reuse:** each workspace has ONE set of shared project agents —
+\`Planner\`, \`Builder\`, \`Reviewer\` — reused across ALL project workflows. Never
+create per-project variants like \`{ProjectName} Builder\`.`;
+/**
+ * Write the Contextium instructions as a managed, marker-delimited block into
+ * `filePath`. Re-running replaces the block in place rather than duplicating it,
+ * and any surrounding user content is preserved. Creates the file (and parent
+ * dirs) if missing.
+ *
+ * @param header Optional leading line written above the block on first creation
+ *   only (e.g. a frontmatter fence for operators that require one).
+ */
+export async function writeInstructionsBlock(filePath, opts = {}) {
+    const block = `${INSTRUCTIONS_START}\n${CONTEXTIUM_INSTRUCTIONS}\n${INSTRUCTIONS_END}`;
+    let content = '';
+    try {
+        content = await fs.readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const start = content.indexOf(INSTRUCTIONS_START);
+    const end = content.indexOf(INSTRUCTIONS_END);
+    if (start !== -1 && end !== -1) {
+        content = content.slice(0, start) + block + content.slice(end + INSTRUCTIONS_END.length);
+    }
+    else {
+        const prefix = opts.header && content.length === 0 ? opts.header + '\n\n' : '';
+        const sep = content.length && !content.endsWith('\n') ? '\n\n' : content.length ? '\n' : '';
+        content = prefix + content + sep + block + '\n';
+    }
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, 'utf-8');
+}
+/**
+ * Copy the bundled /ium: command files into an operator's command/prompt
+ * directory. Mirrors what setup-claude installs to ~/.claude/commands/ium/.
+ *
+ * @param srcDir   Directory holding the source `*.md` command files (skills/ium).
+ * @param destDir  Operator command directory to copy into (created if missing).
+ * @param opts.rename  Optional fn to map a source filename to the operator's
+ *   expected name (e.g. Copilot wants `foo.prompt.md`).
+ * @returns the number of command files installed (0 if the source is absent).
+ */
+export async function installCommands(srcDir, destDir, opts = {}) {
+    let files;
+    try {
+        files = (await fs.readdir(srcDir)).filter(f => f.endsWith('.md'));
+    }
+    catch {
+        return 0; // source dir may not exist in older installs — non-fatal
+    }
+    if (files.length === 0)
+        return 0;
+    await fs.mkdir(destDir, { recursive: true });
+    await Promise.all(files.map(f => {
+        const dest = opts.rename ? opts.rename(f) : f;
+        return fs.copyFile(path.join(srcDir, f), path.join(destDir, dest));
+    }));
+    return files.length;
+}
+//# sourceMappingURL=instructions.js.map

package/dist/lib/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/lib/instructions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextium/cli",
-  "version": "1.6.4",
+  "version": "1.6.6",
   "description": "Command-line tool for managing Contextium documentation, agents, skills, and workflows — pipe context to AI coding assistants",
   "keywords": [
     "contextium",

package/skills/ium/new-project.md

@@ -1,6 +1,6 @@
 ---
 name: ium:new-project
-description: Set up a new Contextium project — authenticate, pick a workspace, describe project, intelligently suggest and create libraries, agents, skills, tags, and a workflow. SUGGEST (proactively ask, don't auto-run) when the user seems to be starting a new project or exploring how to organise their AI context — for example: "I'm starting a new project", "I want to get organised with AI", "how do I get the most out of Claude for my project", "I want Claude to know about my project", "I want to set up AI properly for my work", "I need a way for AI to understand my codebase". In these cases ask: "Would you like to set up a Contextium project? I can create libraries, agents, and skills tailored to what you're building — so any AI in your workflow has the right context automatically." — then wait for confirmation. TRIGGER when user says things like: "set up Contextium", "start a new Contextium project", "create a new project in Contextium", "I want to use Contextium", "get started with Contextium", "initialise Contextium for my project", "configure Contextium for me", "connect my project to Contextium", "onboard to Contextium", "set up my Contextium workspace", "create libraries and agents for my project", "I'm new to Contextium help me get set up", "create a Contextium project from scratch", "set up everything in Contextium for me", "help me configure Contextium".
+description: Set up a new Contextium project — authenticate, pick a workspace, describe project, intelligently suggest and create libraries, agents, skills, tags, and a workflow. SUGGEST (proactively ask, don't auto-run) when the user seems to be starting a new project or exploring how to organise their AI context — for example: "I'm starting a new project", "I want to get organised with AI", "how do I get the most out of Claude for my project", "I want Claude to know about my project", "I want to set up AI properly for my work", "I need a way for AI to understand my codebase". In these cases ask: "Would you like to set up a Contextium project? I can create libraries, agents, and skills tailored to what you're building — so any AI in your workflow has the right context automatically." — then wait for confirmation. TRIGGER when user says things like: "set up Contextium", "start a new Contextium project", "create a new project in Contextium", "I want to use Contextium", "get started with Contextium", "initialise Contextium for my project", "configure Contextium for me", "connect my project to Contextium", "onboard to Contextium", "set up my Contextium workspace", "create libraries and agents for my project", "I'm new to Contextium help me get set up", "create a Contextium project from scratch", "set up everything in Contextium for me", "help me configure Contextium". ALSO TRIGGER for starting a project from an idea — "I have an idea about X", "I have an idea for X", "I want to start a project on X", "start a project: X", "let's flesh out an idea", "I want to build X" — these begin a new project; for a brand-new idea (not a feature in an existing product) the flow runs a full business analysis (SWOT, market size, competitor analysis with their funding/revenue, market-entry difficulty, two-tier financials, RICE, timeline, roles) and a synthesised go/no-go verdict before planning the build.
 allowed-tools:
   - Bash
   - mcp__contextium__list_workspaces
@@ -16,7 +16,11 @@ allowed-tools:
   - mcp__contextium__list_tag_types
   - mcp__contextium__create_tag
   - mcp__contextium__create_tag_type
+  - mcp__contextium__create_file
+  - mcp__contextium__add_phase
+  - mcp__contextium__load_workflow
   - AskUserQuestion
+  - WebSearch
   - WebFetch
 ---
 
@@ -114,6 +118,49 @@ Ask the user this question exactly:
 Wait for their response. Store it as the project description. Do not proceed until you have a meaningful answer.
 </step>
 
+<step name="branch_gate">
+Decide whether this is a **new idea/venture** (needs a full business analysis) or a **new feature inside an existing product** (skip the analysis — you're already in that market). Score the signals into a confidence, then either confirm a clear lean with one pre-answered question, or — if it's genuinely a toss-up — ask the user straight. Do not interrogate the user cold when the signals are clear.
+
+**`feature` signals — but only when the existing context looks *established*:**
+- An existing workflow was selected in `existing_workflow_check` AND that workflow looks established — it has build history (phases or a populated project-state), or libraries with real code/architecture docs, or a name/description that denotes a concrete product or feature area.
+- `has_codebase_scan == true` (a mapped codebase exists).
+- The description frames an addition to something that already exists — "add … to my app", "a new feature for …", "improve the … in our product", "extend …".
+
+**`idea` signals:**
+- Fresh workspace / no existing workflow chosen, `has_codebase_scan == false`, and the description frames a brand-new product, business, book, or venture — "I have an idea for …", "I want to start a …", "build a new …".
+- **An existing workflow was selected but it is NOT established** — it is empty (0 phases, no meaningful libraries/files) or its name/description reads like an idea bucket (matches words like *ideas, idea, concept, concepts, business plan, business plans, brainstorm, backlog, someday, pipeline, ventures, R&D, discovery, exploration*). Selecting such a container is a signal someone is starting a NEW idea, not extending a product — do not treat it as `feature`.
+
+**Resolve to a confidence:**
+- If feature signals clearly outweigh idea signals → confident `feature`.
+- If idea signals clearly outweigh feature signals → confident `idea`.
+- If signals are mixed, weak, or contradictory (e.g. an existing-but-empty workflow plus a description that could be read either way) → **undetermined**.
+
+**Then:**
+
+- Confident `feature` — confirm, feature first (Recommended):
+  "This looks like a feature inside an existing product, so I'd skip the market/competitor/financial analysis and go straight to planning the build. Sound right?"
+  - "Yes — it's a feature, just plan the build (Recommended)"
+  - "No — it's a new idea, run the full business analysis"
+
+- Confident `idea` — confirm, idea first (Recommended):
+  "This looks like a brand-new idea. I can run a full business analysis first — is it worth doing, how hard is the market to break into, who are you up against, and what would it cost — before planning the build. Want that?"
+  - "Yes — run the full business analysis (Recommended)"
+  - "No — skip it, just plan the build"
+
+- **Undetermined** — ask neutrally, with NO option marked Recommended (a wrong nudge is the thing to avoid here):
+  "Quick check so I set this up right — is this a brand-new idea you want me to validate first, or a feature/addition to something you're already building?"
+  - "A new idea — run the full business analysis"
+  - "A feature/addition — just plan the build"
+
+Store the result as `track = "idea"` or `track = "feature"`. This drives the rest of the session:
+- `track == "idea"` → the **business-analysis pipeline** runs (SWOT, market, competitor, financials, RICE, timeline, roles, and a synthesised verdict), and the Researcher agent is created automatically and put to work — so do NOT ask the standalone "want a research agent?" question later; it is absorbed here.
+- `track == "feature"` → skip the business analysis entirely. Produce only the build plan + RICE + timeline. The standalone "want a Researcher agent?" question still applies (as a standing capability for technical lookups during the build).
+
+**Idea-in-a-container:** if the idea track was reached because an existing workflow was selected but it is an empty or idea-bucket container (per the idea signals above), set `idea_container_workflow = <that workflow's name/id>`. The container is NOT this idea's home — the new idea gets its OWN dedicated library (already the rule: one library per project) and its OWN dedicated workflow (handled in `workflow_prompt`). The container is treated as an index of ideas, not the project to extend. If no container was involved, leave `idea_container_workflow` unset.
+
+Do not show the inference reasoning to the user — just ask the confirmation question.
+</step>
+
 <step name="quiet_analysis">
 Silently fetch all existing workspace resources. Do not show raw output or errors. Show only these progress lines as you go:
 
@@ -200,7 +247,11 @@ Wait for the user to confirm, adjust, or say skip on any item before proceeding.
 </step>
 
 <step name="research_question">
-Ask the user:
+**Track-aware.**
+
+**If `track == "idea"`:** do NOT ask this question. The business analysis (run later in the `business_analysis` step) *is* research, and it runs through the Researcher — so the Researcher is implied. Silently add a "**[Project Name] Researcher**" agent to the creation plan, tailored to this idea's domain (market, competitor, and feasibility research), and set `research_agent_planned = true`. Note internally that this Researcher is the agent the `business_analysis` pipeline runs as. Continue without prompting.
+
+**If `track == "feature"`:** ask the standalone question, because there's no business analysis but a researcher may still be useful for technical/competitive lookups during the build:
 
 "Does this project need research before you start work? I can create a dedicated research agent to gather information, analyse sources, and summarise findings for your project."
 
@@ -208,7 +259,7 @@ Use AskUserQuestion:
 - "Yes, add a research agent"
 - "No, skip"
 
-If yes: add a project-specific research agent to the creation plan. Name it something like "**[Project Name] Researcher**" and tailor its system prompt to the specific research domain (e.g. competitor analysis, technical investigation, market research — infer from the project description). Store this agent as `research_agent_planned = true` for use in later steps.
+If yes: add a project-specific research agent to the creation plan. Name it something like "**[Project Name] Researcher**" and tailor its system prompt to the specific research domain (e.g. competitor analysis, technical investigation — infer from the project description). Store this agent as `research_agent_planned = true` for use in later steps.
 
 If no: set `research_agent_planned = false` and continue.
 </step>
@@ -392,7 +443,238 @@ contextium tag-type create "<name>" --workspace <slug>
 **MCP:** use the corresponding create_* tools for each resource type.
 </step>
 
+<step name="business_analysis">
+**Only runs when `track == "idea"`.** If `track == "feature"`, skip this entire step.
+
+This is the business-analysis pipeline — it produces the discovery documents that answer "is this idea worth doing, and how hard is the market to break into?" It runs **as the Researcher agent** created in `research_question`: adopt that agent's perspective for the analysis. Every document is written as a **file** in the project library (the single library in `created_library_ids`), never as agent text or phases, so it costs nothing at workflow-load time. Tag each file `type:business-analysis` (create the `type` tag-type and the `business-analysis` value once per workspace, then reuse) so the documents retrieve on demand and stay out of default context loading.
+
+**Load-cost guard:** analysis output must stay as files + (for the build plan) short DB phases only. Never write analysis prose into agent system prompts, task records, or phase descriptions — those load on every `load_workflow`, whereas files and tags do not. Done right, a project with the full analysis loads no heavier than one without it.
+
+Generate the documents below **in order** — the build plan feeds RICE, the build plan + roles feed financials, and every document feeds the final verdict, so do not reorder. Use **live web search** for the market and competitor documents (real, current figures — cite sources inline). Keep every document concrete to *this* idea and in plain English.
+
+**SWOT analysis → `01-swot.md`**
+
+Write a SWOT grounded in *this* project's description (and the codebase-scan context if `has_codebase_scan == true`) — not generic boilerplate. Plain English, concrete to the idea. Use this structure:
+
+```markdown
+# SWOT Analysis — [Project Name]
+
+> Part of the business analysis. Read alongside the market, competitor, and financial documents; the verdict (00-verdict.md) synthesises all of them.
+
+## Strengths
+Internal advantages this idea/team starts with. 3–5 specific bullets.
+
+## Weaknesses
+Internal gaps, missing capabilities, or constraints. 3–5 specific bullets — be honest, not flattering.
+
+## Opportunities
+External openings: market gaps, trends, underserved segments, timing. 3–5 bullets.
+
+## Threats
+External risks: incumbents, market shifts, regulation, dependencies. 3–5 bullets.
+
+## Takeaway
+2–3 sentences: what the SWOT implies for whether and how to pursue this.
+```
+
+Write the file into the project library:
+
+**CLI:**
+```bash
+cat << 'EOF' | contextium new "<project-library-name>" -t "SWOT Analysis — [Project Name]" -p "01-swot.md" --stdin -w <workspace>
+<generated SWOT content>
+EOF
+```
+**MCP:** call mcp__contextium__create_file with `libraryId` = the project library ID, `title` = "SWOT Analysis — [Project Name]", `path` = "01-swot.md", and the generated content.
+
+Then apply the `type:business-analysis` tag to the file. Show `✓ Created SWOT analysis "01-swot.md"` when done. Suppress errors silently and note any failure in the summary.
+
+**Market research (live web) → `02-market-research.md`**
+
+Use live web search for current figures; cite sources inline. Structure:
+
+```markdown
+# Market Research — [Project Name]
+
+## Market Size
+- **TAM** (total addressable market): $X — [basis + source]
+- **SAM** (serviceable addressable market): $X — [basis]
+- **SOM** (realistic obtainable share, year 1–2): $X — [basis]
+
+## Trends & Demand Signals
+3–5 bullets on where the market is heading and evidence of real demand (search volume, funding flowing in, adoption data) — each with a source.
+
+## Target Segments
+Who actually buys/uses this, ranked by attractiveness.
+
+## Takeaway
+2–3 sentences: is the prize big enough to be worth chasing?
+```
+Write to the project library (`02-market-research.md`), tag `type:business-analysis`. Show `✓ Created market research "02-market-research.md"`.
+
+**Competitor analysis (live web) → `03-competitor-analysis.md`**
+
+Use live web search. For each named competitor include their **financials** — they directly inform how hard the market is to enter:
+
+```markdown
+# Competitor Analysis — [Project Name]
+
+## Named Competitors
+For each (aim for 4–8):
+### [Competitor]
+- **What they do / positioning:**
+- **Strengths:**
+- **Weaknesses / gaps:**
+- **Funding raised:** $X ([round], [source])
+- **Revenue / ARR (if known):** $X ([source])
+- **Valuation (if known):** $X ([source])
+
+## The Gap / Wedge
+Where is the opening this idea could enter through? Be honest — if there's no obvious wedge, say so.
+
+## Takeaway
+2–3 sentences on how crowded and well-funded the field is.
+```
+Write to `03-competitor-analysis.md`, tag `type:business-analysis`. Show `✓ Created competitor analysis "03-competitor-analysis.md"`.
+
+**Build plan → `04-build-plan.md` + DB phases**
+
+Break the idea into the natural unit of work for its type — software → development phases, a book → chapters, a campaign → workstreams, etc. (detect from the description). For each item: a title, a one-line description, and a rough effort sense (used by RICE and the timeline). Structure:
+
+```markdown
+# Build Plan — [Project Name]
+
+Unit type: [phases | chapters | workstreams | …]
+
+1. **[Item title]** — [one-line description] · effort: [S/M/L]
+2. …
+```
+Write to `04-build-plan.md`, tag `type:business-analysis`. Then **also create each item as a DB phase** of THIS project's plan via `add_phase` (short title + one-line description only — keep RICE/timeline detail in the files, not the phase records). Show `✓ Created build plan "04-build-plan.md" (N phases)`.
+
+**RICE scorecard → `05-rice-scorecard.md`**
+
+Score every build-plan item. RICE = (Reach × Impact × Confidence) ÷ Effort. Use a table, sorted by score descending:
+
+```markdown
+# RICE Scorecard — [Project Name]
+
+> Scores the build-plan items by value vs effort. Reach (people/period), Impact (0.25–3), Confidence (50–100%), Effort (person-weeks or person-months — state the unit).
+
+| Item | Reach | Impact | Confidence | Effort | RICE | Notes |
+|------|-------|--------|------------|--------|------|-------|
+| … | | | | | | |
+
+## What to do first
+2–3 sentences: which items the scores say to prioritise, and which to defer.
+```
+Write to `05-rice-scorecard.md`, tag `type:business-analysis`. Show `✓ Created RICE scorecard "05-rice-scorecard.md"`.
+
+**Timeline → `06-timeline.md`**
+
+Turn the build plan + effort into a realistic schedule:
+
+```markdown
+# Timeline — [Project Name]
+
+| Phase/Item | Duration | Depends on | Milestone |
+|------------|----------|------------|-----------|
+| … | | | |
+
+**Estimated time to first usable version:** [X weeks/months]
+**Estimated time to full scope:** [X]
+
+## Assumptions
+Team size and any assumptions the estimate rests on.
+```
+Write to `06-timeline.md`, tag `type:business-analysis`. Show `✓ Created timeline "06-timeline.md"`.
+
+**Roles → `07-roles.md`**
+
+What roles/skills the project needs to actually ship — feeds the financials:
+
+```markdown
+# Roles Needed — [Project Name]
+
+For each role: what they do, when they're needed, and whether it can be a human hire, an AI agent, or both.
+
+| Role | Responsibility | When | Human / AI / Both |
+|------|----------------|------|-------------------|
+| … | | | |
+
+## Minimum viable team
+The smallest set of roles needed to ship the lean version.
+```
+Write to `07-roles.md`, tag `type:business-analysis`. Show `✓ Created roles "07-roles.md"`.
+
+**Two-tier financials → `08-financials.md`**
+
+Two realistic scenarios. Cost the roles from `07-roles.md`, the hosting/tooling the build plan implies, and a monthly AI line. Use current, realistic figures (live web search for tool/infra/salary benchmarks where helpful).
+
+```markdown
+# Financials — [Project Name]
+
+## Tier 1 — Lean MVP (minimum to build & ship)
+| Line item | One-time | Monthly |
+|-----------|----------|---------|
+| Servers / hosting | | |
+| Tools / licences | | |
+| Labour — [role] (human hire) | | |
+| Labour — [role] (done with AI) | | |
+| AI usage (monthly) | | |
+| … | | |
+| **Totals** | **$X upfront** | **$Y/mo** |
+
+## Tier 2 — Production-grade (fully secure, scalable, no expense spared)
+Same table shape — redundancy, security, scale, full team.
+| **Totals** | **$X upfront** | **$Y/mo** |
+
+## Read
+2–3 sentences comparing the two: what the extra spend buys, and which fits the idea's stage.
+```
+Write to `08-financials.md`, tag `type:business-analysis`. Show `✓ Created financials "08-financials.md"`.
+
+**Verdict synthesis → `00-verdict.md` (generated LAST)**
+
+The headline. Synthesise everything above into one page — this is what the user actually wants:
+
+```markdown
+# Verdict — [Project Name]
+
+## Worth doing?
+**[Go / Go with caveats / Reconsider]** — 2–3 reasons drawn from RICE, financials, and market.
+
+## Market entry difficulty: [N]/10
+Why: saturation, how entrenched and well-funded the incumbents are (from competitor financials), and the barriers (capital, network effects, brand, regulation, switching costs).
+
+## What you're up against
+The key competitors and the wedge you'd enter through — or an honest "no obvious wedge".
+
+## What it'll cost to find out
+The lean-MVP number from the financials.
+
+## Bottom line
+> Market is ~$X. Incumbents funded to ~$Y → difficulty N/10. Entry costs ~$Z lean / ~$W production. **Verdict: …**
+```
+Write to `00-verdict.md`, tag `type:business-analysis`. Show `✓ Created verdict "00-verdict.md"`.
+
+After the verdict, tell the user plainly: "I've written a full business analysis into your library — start with **00-verdict.md** for the go/no-go, then dig into the supporting documents." Do not paste the documents into chat; point to them.
+</step>
+
+<step name="feature_build_plan">
+**Only runs when `track == "feature"`.** If `track == "idea"`, skip this step (the `business_analysis` step already produced the build plan, RICE, and timeline).
+
+A feature inside an existing product doesn't need market/competitor/financial analysis — you're already in that market. It needs to answer "is this feature worth building vs. the other things on the list, and how long will it take?" Produce only three documents, as files in the project library tagged `type:business-analysis`, using the **same formats** defined in the `business_analysis` step:
+
+1. **Build plan → `04-build-plan.md`** (+ create each item as a DB phase via `add_phase`, short title + one-line description).
+2. **RICE scorecard → `05-rice-scorecard.md`** (scores the build-plan items — this is the core "worth it?" answer for a feature).
+3. **Timeline → `06-timeline.md`**.
+
+Do NOT produce SWOT, market, competitor, financials, or a verdict. Show a `✓ Created …` line for each, then tell the user: "I've planned the build — see **04-build-plan.md**, with priorities in **05-rice-scorecard.md** and the schedule in **06-timeline.md**." Suppress errors silently.
+</step>
+
 <step name="workflow_prompt">
+**Dedicated workflow for ideas started in a container.** If `idea_container_workflow` is set (the user entered through an empty/idea-bucket workflow), do NOT extend that container. This idea gets its own dedicated workflow. Default the suggested workflow name to the idea/project name and tell the user plainly: "I'll give this idea its own workflow so its analysis and plan stay self-contained — your '<container name>' workflow stays as an index." After creating the dedicated workflow, optionally add a one-line pointer to the new idea in the container's library (an index entry: idea name + link to its library), if the container has a library. Do not move or copy the analysis docs into the container.
+
 After all other resources are created, ask the user:
 
 "Would you like me to create a workflow to bundle everything together for quick loading? If yes, what would you like to call it?"
@@ -401,6 +683,8 @@ Use AskUserQuestion with two options:
 - "Yes, create a workflow" (and ask for the name as a follow-up if they say yes)
 - "No, skip workflow"
 
+(When `idea_container_workflow` is set, treat "yes" as the default and pre-fill the name with the idea/project name — creating the dedicated workflow is the recommended path, not reusing the container.)
+
 If they say yes and provide a name, create the workflow — **always pass all tracked resource IDs**:
 
 **CLI:**

package/skills/ium/workflow.md

@@ -92,13 +92,13 @@ Workflow loaded. What would you like to do?
 
 The tasks/phases in the session context come from the `load_workflow` response — do NOT call `list_tasks` to fetch them again.
 
-**For project workflows** (`projectConfig.contextLibraryId` is set): tasks are stored as phase files in the Project Library. Surface only the **next pending phase** (first `not_started` task from the loaded data) — do not list all phases.
+**For project workflows** (`projectConfig.contextLibraryId` is set): phases are database records (the `workflow_phases` table), managed with the `add_phase` / `list_phases` / `update_phase_status` MCP tools — NOT files in a library. Surface only the **next pending phase** (first `not_started` phase from the loaded data) — do not list all phases.
 
 5. After outputting the session context block, apply task awareness:
 
 - If there is an **in_progress** task: note it as the active phase and ask if the user wants to resume it.
 - If there is a **not_started** next phase: present it as the suggested next action. Do not auto-start — let the user confirm.
-- If you create new action items during the session: call `add_task` to record them. For project workflows these are stored as phase files in the Project Library — no separate "plan" step needed.
+- If you create new action items during the session: call `add_phase(workflowId, title, ...)` to record them as phases (DB records) — no separate "plan" step and no files needed.
 - When a task/phase is complete: call `update_task_status(taskId, 'done')`.
 - Do not work on multiple tasks simultaneously.
 
@@ -121,16 +121,14 @@ Once the workflow is loaded and the user states what they want to do, apply this
 Assess the scope of the request silently, then act accordingly:
 
 **Simple / single task** (one clear, bounded piece of work — e.g. "fix this bug", "write a readme", "add a button"):
-- Create 1 phase file in the Project Library
-- Call `update_workflow` with `projectConfig: { phaseCount: 1, completedCount: 0, contextLibraryId: "<projectLibraryId>" }`
+- Call `add_phase(workflowId, title)` once to create the phase (a DB record — `add_phase` lazily creates the project plan if none exists)
 - Say: "Added as 1 phase. Starting now." — then proceed immediately as the Builder
 
 **Complex / multi-part ask** (a feature, a new system, multiple steps — e.g. "build an onboarding flow", "add payments", "create the admin panel"):
 - Break the work down into logical phases (DB migrations first, then API, then MCP/CLI, then UI — in dependency order)
 - Aim for 3–10 phases. Each phase = one coherent unit of work that can be built and reviewed independently
-- Create one phase file per phase in the Project Library using `contextium new "<project-library>" -w <workspace> --stdin`
-  Each file must include: phase ID (e.g. `phase-001`), title, layer, status (`pending`), and a brief implementation spec
-- Call `update_workflow` with `projectConfig: { phaseCount: <N>, completedCount: 0, contextLibraryId: "<projectLibraryId>" }`
+- Create one phase per phase by calling `add_phase(workflowId, title, description)` — once per phase. Each phase is a DB record (the `workflow_phases` table); do NOT create files. Put the title and a brief implementation spec (layer, what to build) in the `description`.
+- `phaseCount`/`completedCount` are maintained by the phase tools — you do NOT need to call `update_workflow` to set them
 - Show the user the phase breakdown:
   ```
   Planned X phases:
@@ -143,17 +141,17 @@ Assess the scope of the request silently, then act accordingly:
 
 **If `phaseCount > 0` (phases already exist):**
 - Do NOT re-plan. Go straight to the next pending phase.
-- If the user's request is new work unrelated to existing phases: create a new phase file, increment `phaseCount` via `update_workflow`, and begin it.
+- If the user's request is new work unrelated to existing phases: call `add_phase(workflowId, title)` to add it and begin it.
 
 **Completing phases:**
-- When a phase is done, call `mark_phase_complete` (MCP) or `update_workflow` with `completedCount` incremented
+- When a phase is done, call `update_phase_status(phaseId, 'done')` (or `mark_phase_complete`) — the completed count updates automatically
 - Announce progress: "Phase 2 of 5 complete." then ask if the user wants to continue to the next phase
 - Do not auto-start the next phase without confirmation
 
 **Rules:**
 - Never ask the user "should I plan this?" — just assess and act
-- Never show raw file creation output — only the phase list summary
-- Phase files go in the Project Library (the library whose name contains "Project Library")
+- Phases are DB records — never create files for them; always use `add_phase` / `list_phases` / `update_phase_status`
+- Never show raw tool output — only the phase list summary
 - Keep phase titles short and action-oriented (e.g. "Add payments table migration", "Build checkout API endpoint")
 </auto-planning>