@contextium/cli 1.0.17 → 1.0.19

package/skills/ium/resume-project.md

@@ -1,127 +0,0 @@
----
-name: ium:resume-project
-description: Resume a Contextium project from a session handoff — loads the project plan, finds the last handoff note, and picks up exactly where you left off
-allowed-tools:
-  - Bash
-  - mcp__contextium__list_workflows
-  - mcp__contextium__load_workflow
-  - mcp__contextium__list_context_libraries
-  - mcp__contextium__list_files
-  - mcp__contextium__get_file
-  - mcp__contextium__update_file
-  - AskUserQuestion
----
-
-<objective>
-Resume a project session from a handoff note — load the workflow, read the project plan, find where work stopped, and brief the user so they can continue without losing context.
-</objective>
-
-<process>
-
-<step name="load_workflow">
-If a workflow is already loaded in this session, skip this step.
-
-Otherwise, list available workflows and ask the user which project to resume:
-
-**CLI:** `contextium workflows list -w <workspace> 2>/dev/null`
-**MCP:** call mcp__contextium__list_workflows
-
-Ask: "Which project would you like to resume?"
-
-Load the chosen workflow silently:
-
-**CLI:** `contextium workflow "<name>" -w <workspace> --sync 2>/dev/null`
-**MCP:** call mcp__contextium__load_workflow
-</step>
-
-<step name="find_project_state">
-Contextium is the source of truth. Always read from there first.
-
-**1. Contextium first** — search the loaded workflow's libraries for `project-state.md`:
-
-**CLI:** `contextium find "project-state" -w <workspace> 2>/dev/null`
-**MCP:** search list_files across the workflow's libraries for a file with path matching `project-state.md`
-
-If found, fetch the full content:
-
-**CLI:** `contextium cat <fileId> -w <workspace> 2>/dev/null`
-**MCP:** call mcp__contextium__get_file with the file ID
-
-**2. Legacy fallback** — if `project-state.md` is not found, search for the older `project-plan.md` filename in the same libraries and treat it the same way.
-
-**3. Not found** — if not found in Contextium, tell the user:
-"No project state found in your Contextium workspace. If you set up this project with `/ium:new-project`, the state should be in one of your libraries. Would you like me to search the full workspace?"
-</step>
-
-<step name="parse_state">
-Read the project state file and extract:
-
-1. **Current Position** — from the `## Current Position` section: current phase name, status, and next action
-2. **Handoff note** — look for a `> Session Handoff` block under the current phase. Contains what was completed, decisions made, what's needed next, open questions
-3. **Completed phases** — all phases marked "Complete"
-4. **Remaining phases** — all phases still "Not Started" or "In Progress"
-5. **Recent decisions** — the last 3 entries from the `## Decisions Log` table (if it exists and has entries)
-6. **Pending seeds** — any entries in the `## Seeds` table (surface only if relevant to the current phase)
-
-Present a clear resumption brief:
-
-```
-── Resuming: [Project Name] ──────────────────────
-
-Completed:
-  ✓ Phase 1: [Name]
-  ✓ Phase 2: [Name]
-
-Current:
-  → Phase 3: [Name] — In Progress
-  Next action: [from Current Position]
-
-Last session notes:
-  [Handoff note content, or phase description if no handoff]
-
-Up next:
-  [What the handoff says needs to happen]
-
-Remaining:
-  ○ Phase 4: [Name]
-  ○ Phase 5: [Name]
-
-Locked decisions:
-  • [Decision] — [Rationale]
-  • [Decision] — [Rationale]
-
-─────────────────────────────────────────────────
-```
-
-Only show the "Locked decisions" section if the Decisions Log has entries — these are facts the session must not re-debate.
-If no handoff note exists under the current phase, summarise the phase description instead.
-</step>
-
-<step name="confirm_and_continue">
-Ask the user:
-
-"Ready to continue with Phase [N]: [Name]?"
-
-Use AskUserQuestion:
-- "Yes, let's go"
-- "Give me a summary of what we're building first"
-- "I want to start a different phase"
-
-If "Yes, let's go": activate the appropriate agent(s) from the loaded workflow and begin the phase work. Update the phase status in `project-state.md` to "In Progress" if it isn't already.
-
-If "Give me a summary": provide a concise overview of the full project and current phase goals drawn from the plan, then ask again if they're ready to continue.
-
-If "I want to start a different phase": list the available phases and let them pick one. Update that phase to "In Progress" in `project-state.md`.
-</step>
-
-</process>
-
-<rules>
-- Never show raw file IDs, API responses, or CLI output to the user
-- Always load the workflow before reading the project state — never search the full workspace without it
-- If the state file has no handoff note, still resume gracefully using the phase description and Current Position
-- When continuing work, always update `## Current Position` and phase status in `project-state.md` in Contextium
-- Decisions in the `## Decisions Log` are locked — surface them in the resumption brief so the session starts with full context, but never re-debate them unless the user explicitly asks to
-- At the end of each phase, follow the session usage check rule — if above 50%, write a new handoff note and update Current Position in Contextium, then prompt the user to start a fresh session with `/ium:resume-project`
-- If all phases are marked "Complete" when reading the state, ask the user if they want to convert it into a Product Description document before resuming — do not start new phase work on a completed project without asking
-</rules>

package/skills/ium/scan-existing.md

@@ -1,422 +0,0 @@
----
-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>