@contextium/cli 1.0.21 → 1.0.22

package/skills/ium/scan-existing.md

@@ -0,0 +1,422 @@
+---
+name: ium:scan-existing
+description: Scan an existing codebase and write analysis documents to a Contextium context library — tech stack, architecture, structure, conventions, and concerns. Used before /ium:new-project to generate a roadmap that knows what's already built vs what still needs doing.
+allowed-tools:
+  - Bash
+  - Glob
+  - Grep
+  - Read
+  - mcp__contextium__list_workspaces
+  - mcp__contextium__list_context_libraries
+  - mcp__contextium__list_workflows
+  - mcp__contextium__load_workflow
+  - mcp__contextium__create_context_library
+  - mcp__contextium__create_file
+  - mcp__contextium__update_file
+  - mcp__contextium__list_files
+  - mcp__contextium__get_file
+  - AskUserQuestion
+---
+
+<objective>
+Analyse an existing codebase across five domains and write the findings as structured documents to a Contextium context library. The output gives any agent full context about what exists, how it's built, and what's already working — without re-analysing the codebase every session. When followed by /ium:new-project, the roadmap will know what's already done and only plan phases for what's missing.
+</objective>
+
+<mode-detection>
+Run once at the start, silently:
+
+```bash
+command -v contextium &>/dev/null && echo "cli" || echo "no-cli"
+```
+
+- If `cli`: use CLI commands throughout.
+- If `no-cli`: use MCP tools throughout.
+- If neither: tell the user "Contextium doesn't appear to be installed." and stop.
+</mode-detection>
+
+<process>
+
+<step name="check_auth">
+**CLI only.** Run silently:
+```bash
+contextium whoami 2>/dev/null | grep -E "Token:|Name:" || echo "unauthenticated"
+```
+If unauthenticated or token expired, tell the user to run `contextium login` and stop.
+
+MCP users are already authenticated — skip.
+</step>
+
+<step name="select_library">
+Determine where to write the codebase documents.
+
+If a workflow is already loaded in this session, check whether any of its libraries have an obvious "codebase" or "technical" purpose. If yes, suggest it. If not, ask which library to use.
+
+If no workflow is loaded:
+
+**CLI:** `contextium library list --workspace <slug> 2>/dev/null`
+**MCP:** call mcp__contextium__list_context_libraries
+
+Ask: "Which library should I write the codebase analysis to? Or I can create a new one — for example, 'Codebase Analysis'."
+
+Use AskUserQuestion:
+- Present existing library names
+- "Create a new library for this"
+
+If creating new: use the name the user provides, or default to "[Project Name] Codebase". Create it:
+
+**CLI:** `contextium library create "<name>" --workspace <slug>`
+**MCP:** call mcp__contextium__create_context_library
+
+Store the target library ID as `target_library_id`.
+</step>
+
+<step name="check_existing">
+Check whether any of the five analysis documents already exist in the target library by listing its files and looking for: `stack.md`, `architecture.md`, `structure.md`, `conventions.md`, `concerns.md`.
+
+If any exist, ask:
+
+"I found existing analysis documents in this library. What would you like to do?"
+
+Use AskUserQuestion:
+- "Refresh all documents (overwrite)"
+- "Update specific documents only"
+- "Cancel"
+
+If "Update specific": ask which ones to update. Only run analysis passes for those.
+If "Refresh all" or no existing docs: run all five passes.
+</step>
+
+<step name="orient">
+Before analysing, silently orient yourself to the project. Run:
+
+```bash
+ls -la 2>/dev/null | head -40
+```
+
+Then look for the project's primary language and framework indicators:
+
+```bash
+ls package.json requirements.txt Cargo.toml go.mod pyproject.toml composer.json 2>/dev/null
+```
+
+```bash
+ls -d src/ app/ lib/ pkg/ internal/ api/ 2>/dev/null
+```
+
+Do not show this output to the user. Use it to focus the analysis passes that follow.
+
+Tell the user:
+```
+Scanning codebase — this will take a moment.
+
+  ○ Tech stack & integrations
+  ○ Architecture & structure
+  ○ Conventions & testing
+  ○ Concerns & tech debt
+```
+
+Update each `○` to `✓` as each pass completes.
+</step>
+
+<step name="pass_1_tech">
+**Tech Stack & Integrations**
+
+Analyse and write `stack.md`:
+
+Read dependency manifests:
+```bash
+cat package.json 2>/dev/null
+cat requirements.txt pyproject.toml 2>/dev/null
+cat Cargo.toml go.mod 2>/dev/null
+cat composer.json 2>/dev/null
+```
+
+Read config files:
+```bash
+cat tsconfig.json 2>/dev/null
+ls *.config.* 2>/dev/null
+cat .nvmrc .node-version .python-version 2>/dev/null
+```
+
+Check for external service patterns:
+```bash
+grep -rn "process\.env\." src/ app/ lib/ 2>/dev/null | grep -v "node_modules" | head -40
+cat .env.example .env.sample 2>/dev/null
+```
+
+Produce `stack.md` in this structure:
+
+```markdown
+# Tech Stack
+**Analysis Date:** [today]
+
+## Runtime & Language
+[language, version, runtime]
+
+## Frameworks & Libraries
+[list key dependencies with versions and purpose]
+
+## Build & Tooling
+[build system, bundler, linter, formatter, type checker]
+
+## External Services & Integrations
+[APIs, databases, auth providers, storage, email — with env var names]
+
+## Platform & Deployment
+[inferred from config files — Docker, Vercel, Railway, etc.]
+```
+
+Every item must reference the actual config file or env var it was found in. No vague summaries.
+
+Write to Contextium:
+**CLI:** `cat << 'EOF' | contextium new <library-name> -t "Tech Stack" -p "stack.md" --stdin -w <workspace>`
+**MCP:** call mcp__contextium__create_file (or update_file if refreshing)
+
+Update the progress indicator to `✓ Tech stack & integrations`.
+</step>
+
+<step name="pass_2_architecture">
+**Architecture & Structure**
+
+Analyse and write `architecture.md` and `structure.md`:
+
+Get the full directory tree:
+```bash
+find . -type f -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/.next/*" -not -path "*/build/*" | head -120
+```
+
+Find entry points:
+```bash
+ls src/index.* src/main.* src/app.* src/server.* app/page.* app/layout.* 2>/dev/null
+```
+
+Sample key files to understand patterns:
+```bash
+head -60 $(ls src/index.* src/main.* src/app.* 2>/dev/null | head -3) 2>/dev/null
+```
+
+Produce `architecture.md`:
+
+```markdown
+# Architecture
+**Analysis Date:** [today]
+
+## Pattern
+[MVC / layered / feature-based / monolith / microservices / etc — with evidence]
+
+## Layers
+[list each layer: what it contains, what it depends on, example files]
+
+## Data Flow
+[how a typical request flows through the system — entry point → handler → service → data layer]
+
+## Key Abstractions
+[important interfaces, base classes, shared utilities — with file paths]
+
+## Error Handling
+[how errors propagate — try/catch, result types, middleware, etc.]
+```
+
+Produce `structure.md`:
+
+```markdown
+# Structure
+**Analysis Date:** [today]
+
+## Directory Map
+[annotated directory tree showing purpose of each folder]
+
+## Key File Locations
+| Purpose | Path |
+|---------|------|
+| Entry point | `src/index.ts` |
+| Route definitions | `src/routes/` |
+| [etc] | [etc] |
+
+## Where to Add New Code
+[specific guidance: "New API routes go in src/routes/, follow the pattern in src/routes/users.ts"]
+
+## Naming Conventions
+[file naming, folder naming, component naming patterns with examples]
+```
+
+Write both files to Contextium. Update progress to `✓ Architecture & structure`.
+</step>
+
+<step name="pass_3_conventions">
+**Conventions & Testing**
+
+Analyse and write `conventions.md` and `testing.md`:
+
+Read linting/formatting config:
+```bash
+cat .eslintrc* eslint.config.* .prettierrc* biome.json 2>/dev/null
+```
+
+Sample source files to extract conventions:
+```bash
+head -80 $(find src/ app/ lib/ -name "*.ts" -o -name "*.tsx" -o -name "*.js" 2>/dev/null | grep -v test | grep -v spec | head -5) 2>/dev/null
+```
+
+Check testing setup:
+```bash
+cat jest.config.* vitest.config.* pytest.ini setup.cfg 2>/dev/null
+find . -name "*.test.*" -o -name "*.spec.*" 2>/dev/null | grep -v node_modules | head -20
+```
+
+Produce `conventions.md`:
+
+```markdown
+# Conventions
+**Analysis Date:** [today]
+
+## Naming
+[variables, functions, classes, files, folders — with real examples from the codebase]
+
+## Code Style
+[formatting rules, import order, export patterns — reference linting config]
+
+## Function Design
+[pure vs stateful, async patterns, error handling style]
+
+## State Management
+[how state is managed — context, stores, props — with example file paths]
+
+## Comments & Documentation
+[what gets documented and how]
+```
+
+Produce `testing.md`:
+
+```markdown
+# Testing
+**Analysis Date:** [today]
+
+## Framework & Setup
+[test runner, assertion library, config file location]
+
+## File Organisation
+[where tests live relative to source — colocated, __tests__, etc.]
+
+## Test Structure
+[describe/it patterns, setup/teardown conventions — with example from an existing test]
+
+## Mocking Approach
+[how dependencies are mocked — with example]
+
+## Coverage
+[what's covered, what's not, any coverage thresholds configured]
+
+## How to Run Tests
+[exact commands]
+```
+
+Write both files to Contextium. Update progress to `✓ Conventions & testing`.
+</step>
+
+<step name="pass_4_concerns">
+**Concerns & Tech Debt**
+
+Analyse and write `concerns.md`:
+
+Find tech debt markers:
+```bash
+grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP\|@deprecated" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | grep -v node_modules | head -60
+```
+
+Find large/complex files:
+```bash
+find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" 2>/dev/null | grep -v node_modules | grep -v dist | xargs wc -l 2>/dev/null | sort -rn | head -20
+```
+
+Find empty stubs or incomplete implementations:
+```bash
+grep -rn "throw new Error.*not implemented\|TODO.*implement\|return null\|pass$" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | grep -v node_modules | head -30
+```
+
+Check for hardcoded values that should be config:
+```bash
+grep -rn "localhost\|127\.0\.0\.1\|hardcoded\|magic number" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | grep -v test | head -20
+```
+
+Produce `concerns.md`:
+
+```markdown
+# Concerns & Tech Debt
+**Analysis Date:** [today]
+
+## Tech Debt
+| Issue | Location | Suggested Fix |
+|-------|----------|---------------|
+| [specific issue] | `src/path/file.ts:42` | [concrete fix approach] |
+
+## Known Gaps / Incomplete Features
+[stubs, TODOs marked as incomplete, features with placeholder implementations — file paths required]
+
+## Fragile Areas
+[files or patterns that are high-risk to modify — explain why and how to modify safely]
+
+## Security Observations
+[anything that looks like a security concern — never log secrets, only note patterns]
+
+## Test Coverage Gaps
+[areas with no tests that clearly need them]
+
+## Dependencies to Watch
+[outdated, deprecated, or high-risk dependencies found in package manifest]
+```
+
+Write to Contextium. Update progress to `✓ Concerns & tech debt`.
+</step>
+
+<step name="update_project_state">
+If a `project-state.md` file exists in any library in the loaded workflow, read it and check the `## Phases` section.
+
+For each phase whose described functionality clearly already exists in the codebase (based on what was found in the analysis), add a note under that phase:
+
+```
+> **Already built** — confirmed by codebase scan [date]
+```
+
+And update its status to "Complete" if the entire phase is done.
+
+If no `project-state.md` exists yet, skip this step silently.
+</step>
+
+<step name="summary">
+Show the final summary:
+
+```
+✓ Codebase scan complete
+
+Documents written to "<library name>":
+  ✓ stack.md          — tech stack, dependencies, integrations
+  ✓ architecture.md   — patterns, layers, data flow
+  ✓ structure.md      — directory map, where to add new code
+  ✓ conventions.md    — naming, code style, patterns
+  ✓ testing.md        — test framework, structure, coverage
+  ✓ concerns.md       — tech debt, gaps, fragile areas
+```
+
+Then ask:
+
+"Would you like to set up a new project plan now? Running /ium:new-project will use these documents to understand what's already built and only plan phases for what's missing."
+
+Use AskUserQuestion:
+- "Yes, run /ium:new-project now"
+- "No, I'll do it later"
+
+If yes: proceed with the /ium:new-project flow. The codebase analysis documents are now in the library and will be found automatically when the project state is being planned.
+</step>
+
+</process>
+
+<rules>
+- Never show raw bash output, file paths, or API responses to the user — only the progress indicators and final summary
+- Never read `.env` file contents — only check for the file's existence and read `.env.example` or `.env.sample`
+- Every finding in every document must reference a specific file path — no vague summaries
+- If a pass fails silently (no files found, permission error), write what was found and note "insufficient data to analyse [area]" — never skip the document entirely
+- Documents are written for future AI agents to consume, not as human prose — be specific, prescriptive, and grounded in actual file paths
+- When refreshing, always use update_file not create_file to preserve file history in Contextium
+- Only one set of codebase analysis documents should exist per library — never create duplicates
+</rules>

package/skills/ium/search.md

@@ -10,6 +10,17 @@ Search across Contextium documentation and return matching files with their cont
 </objective>
 
 <process>
+**Step 1 — Check loaded context first**
+If a workflow session context block is active in this conversation, look there first. If the answer is found, respond from it without running any commands.
+
+**Step 2 — Ask before expanding scope**
+If the loaded context doesn't have what the user needs, ask:
+"That's not in the loaded workflow context. Would you like me to search the full workspace?"
+
+Only proceed to step 3 after the user confirms.
+
+**Step 3 — Search the full workspace**
+
 Run a search across the workspace:
 
 ```bash

package/skills/ium/workflow.md

@@ -19,24 +19,32 @@ Load a Contextium workflow and bring its resources into the current context. Onc
 
 Present workflow names only. Ask the user which one to load.
 
-2. Resolve the workspace BEFORE running any command:
-   - If `-w <workspace>` was given in the user's message, use it directly.
-   - Otherwise run: `contextium whoami 2>/dev/null` and extract the `workspace` field.
-   - If that returns nothing, ask the user: "Which workspace should I load this workflow from?"
-   - Do NOT proceed to step 3 until you have a workspace value.
+2. Load the chosen workflow:
 
-3. Load the chosen workflow (workspace is now known):
-
-**CLI:** `contextium workflow "<workflow-name>" -w "<workspace>" 2>/dev/null`
+**CLI:** `contextium workflow "<workflow-name>" -w <workspace> --sync 2>/dev/null`
 **MCP:** call mcp__contextium__load_workflow
 
-Note: `--sync` is optional and only needed if you want to cache files locally. Omit it by default.
+3. Output synced file content to context (CLI only):
+```bash
+contextium cat --all -w <workspace> 2>/dev/null
+```
+
+4. Persist the loaded workspace and workflow to `.contextiumrc` so it can be auto-restored after `/clear`:
 
-4. Output synced file content to context (CLI only):
 ```bash
-contextium cat --all -w "<workspace>" 2>/dev/null
+node -e "
+try {
+  const fs = require('fs');
+  const rc = JSON.parse(fs.readFileSync('.contextiumrc', 'utf8'));
+  rc.last_workflow = '<workflow-name>';
+  rc.last_workspace = '<workspace-slug-or-name>';
+  fs.writeFileSync('.contextiumrc', JSON.stringify(rc, null, 2));
+} catch(e) {}
+" 2>/dev/null
 ```
 
+Do this silently — never mention it to the user.
+
 5. Output a session context block in this exact format so all resource IDs and names are available for the rest of the session without re-querying:
 
 ```
@@ -59,6 +67,7 @@ Workflow loaded. What would you like to do?
 ```
 
 If a workflow name was specified directly in the user's message, skip step 1 and load immediately.
+If no workspace is specified, use the default from .contextiumrc or ask the user.
 </process>
 
 <session-rules>
@@ -69,4 +78,13 @@ Once the session context block has been output, these rules apply for the rest o
 - Do NOT re-verify or re-check which libraries, agents, or skills exist — they are already known
 - All tool calls and checks must be silent — never show the user raw API responses, tool call names, or intermediate results
 - Only surface the final answer or the created/updated content to the user
+
+**Scope rules — what is "available":**
+- When the user asks "what agents/skills/libraries do I have?" or "what's available?" — answer ONLY from the session context block above. Never call list_agents, list_skills, or list_context_libraries to answer this question.
+- If the user asks about something not in the session context, say so and ask if they want you to search the full workspace before doing so.
+
+**Search order:**
+1. Check the loaded session context first
+2. If not found there, say: "That's not in the loaded workflow. Would you like me to search the full workspace?"
+3. Only query the full workspace after the user confirms
 </session-rules>

package/skills/ium/workspace.md

@@ -13,27 +13,28 @@ Switch the active Contextium workspace with full context handoff — save what's
 <process>
 
 <step name="show_current">
-Show the current workspace and list available workspaces:
+Silently fetch the current workspace and available workspaces:
 
 ```bash
-# Show current workspace from .contextiumrc
-cat .contextiumrc 2>/dev/null | grep -E "workspace" | head -5 || echo "No .contextiumrc found"
-
-# List all available workspaces
-contextium workspaces
+cat .contextiumrc 2>/dev/null
 ```
 
+**CLI:** `contextium workspaces 2>/dev/null`
+**MCP:** call mcp__contextium__list_workspaces
+
+Parse the results internally — extract names and slugs only. Never show IDs, UUIDs, or raw command output to the user.
+
 Display clearly:
 ```
 Current workspace: <name>
 
 Available workspaces:
-1. workspace-a
-2. workspace-b
-3. workspace-c
+1. Workspace A
+2. Workspace B
+3. Workspace C
 ```
 
-Ask the user which workspace to switch to using AskUserQuestion with the workspace names as options. If the user already specified one in their message, skip this and use it directly.
+Ask the user which workspace to switch to using AskUserQuestion with workspace **names only** as options — no IDs, no slugs. If the user already specified one in their message, skip this and use it directly.
 </step>
 
 <step name="save_handoff">

package/dist/commands/load-skill.d.ts

@@ -1,3 +0,0 @@
-import { Command } from 'commander';
-export declare const loadSkillCommand: Command;
-//# sourceMappingURL=load-skill.d.ts.map

package/dist/commands/load-skill.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"load-skill.d.ts","sourceRoot":"","sources":["../../src/commands/load-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAQnC,eAAO,MAAM,gBAAgB,SA6BzB,CAAA"}

package/dist/commands/load-skill.js

@@ -1,35 +0,0 @@
-import { Command } from 'commander';
-import fs from 'fs/promises';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import { chalk } from '../lib/output.js';
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export const loadSkillCommand = new Command('load-skill')
-    .description('Output bundled Contextium CLI SKILL.md for local agent context loading')
-    .option('--format <format>', 'Output format (text|json)', 'text')
-    .option('--name <name>', 'Skill name to load', 'contextium-cli')
-    .action(async (options) => {
-    try {
-        if (options.name !== 'contextium-cli') {
-            console.log(chalk.red(`Unknown skill '${options.name}'.`));
-            console.log(chalk.dim('Available skills: contextium-cli'));
-            process.exit(1);
-        }
-        const skillPath = path.join(__dirname, '..', '..', 'skills', 'ium', 'SKILL.md');
-        const content = await fs.readFile(skillPath, 'utf-8');
-        if (options.format === 'json') {
-            console.log(JSON.stringify({
-                name: 'contextium-cli',
-                source: 'skills/ium/SKILL.md',
-                content,
-            }, null, 2));
-            return;
-        }
-        console.log(content);
-    }
-    catch (error) {
-        console.log(chalk.red(`Failed to load skill: ${error.message}`));
-        process.exit(1);
-    }
-});
-//# sourceMappingURL=load-skill.js.map

package/dist/commands/load-skill.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"load-skill.js","sourceRoot":"","sources":["../../src/commands/load-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,MAAM,aAAa,CAAA;AAC5B,OAAO,IAAI,MAAM,MAAM,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAA;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAExC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AAE9D,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,OAAO,CAAC,YAAY,CAAC;KACtD,WAAW,CAAC,wEAAwE,CAAC;KACrF,MAAM,CAAC,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,CAAC;KAChE,MAAM,CAAC,eAAe,EAAE,oBAAoB,EAAE,gBAAgB,CAAC;KAC/D,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;IACxB,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACtC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,kBAAkB,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,CAAA;YAC1D,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC,CAAA;YAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,CAAA;QAC/E,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QAErD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC9B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;gBACzB,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,qBAAqB;gBAC7B,OAAO;aACR,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;YACZ,OAAM;QACR,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACtB,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAyB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;QAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;AACH,CAAC,CAAC,CAAA"}