@contextium/cli 1.0.12 → 1.0.14

package/package.json

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

package/skills/ium/help.md

@@ -31,6 +31,8 @@ CONTENT
   /ium:create          Create an agent, skill, or workflow interactively
   /ium:search          Search docs by query, filename, or tag
   /ium:workflow        Load a workflow and sync its resources into context
+  /ium:resume-project  Resume a project from a session handoff — picks up
+                       exactly where you left off in the project plan
 
 MARKETPLACE
   /ium:marketplace     Browse, install, or publish skills, agents & MCP servers

package/skills/ium/new-project.md

@@ -58,6 +58,40 @@ Ask: "Which workspace is this project for?"
 Present names only — no IDs, no raw output.
 </step>
 
+<step name="existing_workflow_check">
+Before asking for a project description, ask:
+
+"Do you have an existing Contextium workflow you'd like to use as a base for this project?"
+
+Use AskUserQuestion:
+- "Yes, use an existing workflow"
+- "No, start fresh"
+
+If yes:
+1. Silently fetch all workflows in the selected workspace:
+   **CLI:** `contextium workflows list -w <slug> 2>/dev/null`
+   **MCP:** call mcp__contextium__list_workflows
+
+2. Present workflow names and ask: "Which workflow would you like to use?"
+
+3. Load the selected workflow silently and read its resources (libraries, agents, skills).
+
+4. After the user provides their project description (next step), compare the workflow's existing resources against what the new project needs. In the plan step, flag:
+   - Resources that already exist in the workflow and can be reused as-is
+   - Resources that exist but may need updating or extending for this project (flag as "Extend")
+   - Resources that are missing entirely and need to be created
+
+5. In the plan table, add an "Extend" action row type where relevant:
+
+| Action | Name | Purpose |
+|--------|------|---------|
+| Reuse  | "Agent Name" | already covers this need |
+| Extend | "Agent Name" | exists but needs updated system prompt for this project |
+| Create | "Agent Name" | not in the workflow, needs to be created |
+
+If no: continue to project description with a clean slate.
+</step>
+
 <step name="project_description">
 Ask the user this question exactly:
 
@@ -151,13 +185,79 @@ Shall I go ahead and create all of this?
 Wait for the user to confirm, adjust, or say skip on any item before proceeding.
 </step>
 
+<step name="research_question">
+Ask the user:
+
+"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."
+
+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 no: set `research_agent_planned = false` and continue.
+</step>
+
+<step name="planner_question">
+Ask the user:
+
+"Would you like a project planner to break your project into phases and track progress? I'll create a planning agent and a phase tracker document you can follow from start to finish."
+
+Use AskUserQuestion:
+- "Yes, add a project planner"
+- "No, skip"
+
+If yes:
+1. Add a "**[Project Name] Planner**" agent to the creation plan — its role is to define project phases, estimate scope, and guide execution in order. Tailor its system prompt to the project domain. Store as `planner_planned = true`.
+2. After all resources are created, create a planning document file in the most relevant library. The file should contain a phased breakdown of the project inferred from the user's description — structured like:
+
+```markdown
+# [Project Name] — Project Plan
+
+## Phase 1: [Name]
+**Status:** Not Started
+[Brief description of what this phase covers]
+
+## Phase 2: [Name]
+**Status:** Not Started
+[Brief description]
+
+...
+```
+
+Infer sensible phases from the project description. Use "Not Started" for all phases. Title the file something like `project-plan.md`.
+
+If no: set `planner_planned = false` and continue.
+</step>
+
 <step name="create_resources">
-Only create what the user confirmed. Create in this order: tag types → tags → libraries → skills → agents.
+Only create what the user confirmed across all steps. Create in this order: tag types → tags → libraries → skills → agents (including research and planner agents if confirmed).
 
 Do NOT create a workflow in this step.
 
 Show `✓ Created "Name"` for each item as it is created. Show `↗ Reusing "Name"` for each existing resource being included.
 
+If `planner_planned = true`, create the project plan file after all other resources are created:
+
+**CLI:**
+```bash
+cat << 'EOF' | contextium new <library-name> -t "[Project Name] — Project Plan" -p "project-plan.md" --stdin -w <workspace>
+<generated phase content>
+EOF
+```
+**MCP:** call mcp__contextium__create_file with the phase content.
+
+Also write the same content locally to `.ium-planning/project-plan.md` so there is always a local fallback:
+
+```bash
+mkdir -p .ium-planning && cat << 'EOF' > .ium-planning/project-plan.md
+<same generated phase content>
+EOF
+```
+
+Show `✓ Created project plan "project-plan.md"` and `✓ Saved local backup to .ium-planning/project-plan.md` when done.
+
 Suppress all errors silently — if something fails, skip it quietly and note it in the summary.
 
 **CLI commands:**
@@ -165,7 +265,6 @@ Suppress all errors silently — if something fails, skip it quietly and note it
 contextium library create "<name>" --workspace <slug>
 contextium agent create "<name>" --workspace <slug>
 contextium skill create "<name>" --workspace <slug>
-contextium workflow create "<name>" --workspace <slug>
 contextium tag create "<value>" --type <type-slug> --workspace <slug>
 contextium tag-type create "<name>" --workspace <slug>
 ```
@@ -195,6 +294,40 @@ Then automatically load it:
 If they say no, skip workflow creation and loading entirely.
 </step>
 
+<step name="post_workflow_actions">
+This step only runs if `research_agent_planned = true` or `planner_planned = true`.
+
+**If `research_agent_planned = true`:**
+
+Ask the user:
+
+"Would you like to start the research phase now? I can activate the [Project Name] Researcher and begin gathering information based on your project description."
+
+Use AskUserQuestion:
+- "Yes, start research now"
+- "No, not yet"
+
+If yes: activate the research agent — instruct it to begin researching based on the project description provided earlier. Let it run and surface findings to the user. Do not proceed to the planning question.
+
+If no: fall through to the planning question below (if applicable).
+
+---
+
+**If `planner_planned = true` (and research was either not created or the user said no to starting it):**
+
+Ask the user:
+
+"Would you like to plan the project now? The [Project Name] Planner can work through the project description and produce a detailed phase-by-phase plan."
+
+Use AskUserQuestion:
+- "Yes, start planning now"
+- "No, I'll do it later"
+
+If yes: activate the planner agent — instruct it to analyse the project description and produce a detailed phased plan, updating the `project-plan.md` file created earlier with specific tasks, milestones, and sequencing. Let it run and surface the plan to the user.
+
+If no: continue to summary.
+</step>
+
 <step name="summary">
 Show a clean final summary:
 
@@ -226,3 +359,52 @@ If anything failed to create, add a single line at the end:
 - The plan report must explain the reasoning for each item — not just list names
 - Never create anything before the user confirms the plan
 </rules>
+
+<ongoing-project-rules>
+These rules apply for the duration of the project, after setup is complete.
+
+**New suggestions and feature ideas**
+- Whenever a new feature, idea, or suggestion comes up during the project, ask: "Would you like to add this to the project plan to tackle after the current work is done?"
+- If yes: append it to `project-plan.md` as a new phase with status "Not Started"
+- If no: note it and continue with the current work
+
+**Tackling a new feature or setting**
+- When the user is ready to start work on a new feature or area of the project, ask:
+  1. "Would you like to run a research phase on this first?" — if a research agent exists, use it; otherwise offer to create one
+  2. "Would you like a phased plan for this?" — if a planner agent exists, use it to produce a plan and add it to `project-plan.md`; otherwise offer to create one
+- If the user says no to both, continue directly using the existing agents based on their instructions — no extra setup needed
+- Treat each new feature as its own mini-project using the existing workspace resources — never create duplicate agents or skills if suitable ones already exist
+
+**Suggesting new agents and skills**
+- If the work the user is describing would clearly benefit from an agent or skill that doesn't exist yet, proactively suggest creating one — explain what it would do and why it would help
+- Never create new agents or skills without the user's confirmation
+- Always check existing workspace resources before suggesting something new
+
+**Session usage check at end of every phase**
+- At the end of every completed phase, check the current session context usage (visible in the Claude Code status bar as a percentage)
+- If usage is **above 50%**, do the following automatically before prompting the user to continue:
+  1. Write a handoff note into `project-plan.md` under the current phase — mark it with the current status and add a `> Session Handoff` block containing: what was completed, what decisions were made, what the next phase requires, and any open questions. Write this update to **both** the Contextium library file and the local `.ium-planning/project-plan.md` file simultaneously so they stay in sync
+  2. Update the phase status to "In Progress" or "Complete" as appropriate in both locations
+  3. Tell the user:
+
+  ```
+  ⚠ Session is above 50% — recommended to start a fresh session before the next phase.
+
+  A handoff note has been saved to your project plan.
+  Run /ium:resume-project to pick up exactly where you left off.
+  ```
+
+- If usage is **below 50%**, simply confirm the phase is complete and ask if the user is ready to move to the next phase
+- Never skip this check at phase end — even if the user seems eager to continue
+
+**Local project plan — hidden file**
+- The local project plan is stored at `.ium-planning/project-plan.md`. The `.ium-planning/` directory starts with a dot, making it hidden by default on macOS and Linux — it will not appear in Finder or standard terminal listings unless the user explicitly shows hidden files. This is intentional to reduce the chance of accidental deletion.
+- Never tell the user where the file is stored unless they ask — it is a background concern
+
+**Project completion — convert to product description**
+- When all phases in `project-plan.md` are marked "Complete", automatically trigger the following:
+  1. Ask the user: "All phases are complete — congratulations! Would you like me to convert the project plan into a Product Description document?"
+  2. If yes: rewrite the content of `project-plan.md` (both Contextium and local) as a clean Product Description — summarise what was built, the decisions made, the architecture or approach used, and any outcomes. Remove phase status markers. Title it "[Project Name] — Product Description". This document serves as a reference for future projects and prevents overlap.
+  3. If no: leave the plan as-is and congratulate the user
+- Never convert automatically without asking — always get confirmation first
+</ongoing-project-rules>

package/skills/ium/resume-project.md

@@ -0,0 +1,133 @@
+---
+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_plan">
+Check for the project plan in this order:
+
+**1. Local first** — check for `.ium-planning/project-plan.md` in the current directory:
+
+```bash
+cat .ium-planning/project-plan.md 2>/dev/null
+```
+
+If found locally, use it. Show `→ Using local project plan (.ium-planning/project-plan.md)` and skip the Contextium lookup.
+
+**2. Contextium fallback** — if not found locally, search the loaded workflow's libraries:
+
+**CLI:** `contextium find "project-plan" -w <workspace> 2>/dev/null`
+**MCP:** search list_files across the workflow's libraries for a file with path matching `project-plan.md`
+
+If found in Contextium, fetch the full content:
+
+**CLI:** `contextium cat <fileId> -w <workspace> 2>/dev/null`
+**MCP:** call mcp__contextium__get_file with the file ID
+
+Then write it to `.ium-planning/project-plan.md` locally so future sessions have the local copy:
+
+```bash
+mkdir -p .ium-planning && cat << 'EOF' > .ium-planning/project-plan.md
+<fetched content>
+EOF
+```
+
+**3. Not found** — if the plan is in neither location, tell the user:
+"No project plan found locally or in your Contextium workspace. If you set up this project with `/ium:new-project`, the plan should be in `.ium-planning/project-plan.md` or in one of your libraries. Would you like me to search the full workspace?"
+</step>
+
+<step name="parse_handoff">
+Read the project plan and identify:
+
+1. The **current phase** — the last phase marked "In Progress", or the first phase marked "Not Started" if none are in progress
+2. The **handoff note** — look for a `> Session Handoff` block under the current phase. This contains what was completed, decisions made, what's needed next, and open questions
+3. **Completed phases** — all phases marked "Complete"
+4. **Remaining phases** — all phases still "Not Started"
+
+Present a clear resumption brief:
+
+```
+── Resuming: [Project Name] ──────────────────────
+
+Completed phases:
+  ✓ Phase 1: [Name]
+  ✓ Phase 2: [Name]
+
+Current phase:
+  → Phase 3: [Name] — In Progress
+
+Last session notes:
+  [Handoff note content]
+
+Up next:
+  [What the handoff says needs to happen next]
+
+Remaining phases:
+  ○ Phase 4: [Name]
+  ○ Phase 5: [Name]
+
+─────────────────────────────────────────────────
+```
+
+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-plan.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-plan.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 plan — never search the full workspace without it
+- If the project plan has no handoff note, still resume gracefully using the phase description
+- When continuing work, always update phase status in `project-plan.md` to reflect current state — write to both Contextium and `.ium-planning/project-plan.md` simultaneously
+- At the end of each phase, follow the session usage check rule — if above 50%, write a new handoff note to both locations and prompt the user to start a fresh session with `/ium:resume-project`
+- The `.ium-planning/` directory is intentionally hidden (dot-prefixed) — never mention its location unless the user asks
+- If all phases are marked "Complete" when reading the plan, 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>