@contextium/cli 1.0.13 → 1.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextium/cli",
-  "version": "1.0.13",
+  "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:
 
@@ -214,7 +248,15 @@ EOF
 ```
 **MCP:** call mcp__contextium__create_file with the phase content.
 
-Show `✓ Created project plan "project-plan.md"` when done.
+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.
 
@@ -337,4 +379,32 @@ These rules apply for the duration of the project, after setup is complete.
 - 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>