@contextium/cli 1.0.13 → 1.0.15

package/package.json

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

package/skills/ium/contextium.md

@@ -49,6 +49,32 @@ Workspace
 | A role combining multiple skills? | Agent |
 | Ready-to-use context package for a task? | Workflow |
 
+## Contextium Is the Source of Truth
+
+All AI-relevant information — project state, SOPs, constraints, decisions, research, planning — lives in Contextium. It is always written to Contextium first. Local files are only for things that belong in git: source code, config, READMEs.
+
+Never write AI planning or knowledge files locally by default. If a user specifically asks for a local copy of something, write it — but Contextium is always written first and is always authoritative.
+
+This gives users something local file-based tools cannot: state survives machine loss, team members share the same context, and multiple projects run in parallel — one workflow loaded per terminal session — with no interference between them.
+
+## Multi-Project Rule
+
+Each project must have its own dedicated context library. Never mix two projects into one library.
+
+The project state file (`project-state.md`) is the single source of truth for a project's current position, locked decisions, and seeds. **Only one `project-state.md` should ever exist per library.** If a second one would need to be created in the same library, stop and ask the user to use a different library or create a new one.
+
+## Decision Routing
+
+When a significant architectural, technical, or approach decision is made during any session, write it to the `## Decisions Log` in `project-state.md` immediately — no user permission needed. Log it silently and mention it in the phase summary.
+
+A decision qualifies if it:
+- Picks a technology or library
+- Sets an API contract or data model
+- Establishes a pattern future phases will depend on
+- Rules out an approach that was considered
+
+Decisions in the log are **locked**. Future sessions must not re-debate them. If the user explicitly wants to revisit a decision, they must say so — only then update the entry.
+
 ## File Routing — Writing Files When Contextium Is Connected
 
 When the Contextium MCP is connected or the CLI is active, **any time a new file is about to be created**, intercept it with a routing question before writing:

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:
 
@@ -168,7 +202,7 @@ If no: set `research_agent_planned = false` and continue.
 <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."
+"Would you like a project planner to break your project into phases and track progress? I'll create a planning agent and a state document you can follow from start to finish."
 
 Use AskUserQuestion:
 - "Yes, add a project planner"
@@ -176,23 +210,50 @@ Use AskUserQuestion:
 
 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:
+2. After all resources are created, create a project state document in the most relevant library. This is the living memory for the project — not just a phase list. Use this exact structure:
 
 ```markdown
-# [Project Name] — Project Plan
+# [Project Name] — Project State
 
-## Phase 1: [Name]
+## Current Position
+**Phase:** Phase 1: [Name]
+**Status:** Not Started
+**Last Updated:** [today's date]
+**Next Action:** Begin Phase 1
+
+## Phases
+
+### Phase 1: [Name]
 **Status:** Not Started
 [Brief description of what this phase covers]
 
-## Phase 2: [Name]
+### Phase 2: [Name]
 **Status:** Not Started
 [Brief description]
 
 ...
+
+## Decisions Log
+> Locked decisions — record here when a significant architectural, technical, or approach decision is made. Do not re-debate entries in this log.
+
+| Decision | Rationale | Phase |
+|----------|-----------|-------|
+| _(none yet)_ | | |
+
+## Seeds
+> Ideas and suggestions to revisit at the right time — not immediate work.
+
+| Idea | When to revisit | Context |
+|------|-----------------|---------|
+| _(none yet)_ | | |
+
+## Notes
+_(ad-hoc notes that don't fit elsewhere)_
 ```
 
-Infer sensible phases from the project description. Use "Not Started" for all phases. Title the file something like `project-plan.md`.
+Infer sensible phases from the project description. Title the file `project-state.md`.
+
+**Important:** Only one `project-state.md` should ever exist per context library. This is the single source of truth for this project. Never create a second one or split state across multiple files.
 
 If no: set `planner_planned = false` and continue.
 </step>
@@ -204,17 +265,17 @@ 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:
+If `planner_planned = true`, create the project state file in Contextium 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>
+cat << 'EOF' | contextium new <library-name> -t "[Project Name] — Project State" -p "project-state.md" --stdin -w <workspace>
+<generated state content>
 EOF
 ```
-**MCP:** call mcp__contextium__create_file with the phase content.
+**MCP:** call mcp__contextium__create_file with the state content.
 
-Show `✓ Created project plan "project-plan.md"` when done.
+Show `✓ Created project state "project-state.md"` when done.
 
 Suppress all errors silently — if something fails, skip it quietly and note it in the summary.
 
@@ -281,7 +342,7 @@ 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 yes: activate the planner agent — instruct it to analyse the project description and produce a detailed phased plan, updating the `project-state.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>
@@ -322,19 +383,54 @@ If anything failed to create, add a single line at the end:
 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"
+- Whenever a new feature, idea, or suggestion comes up during the project, ask: "Would you like to add this to the project state as a seed to revisit later?"
+- If yes: append it to the `## Seeds` section of `project-state.md` in Contextium with a "When to revisit" trigger (e.g. "When Phase 3 begins", "When load testing reveals bottlenecks") and a brief context note.
 - 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
+- Seeds are NOT immediate work — never promote a seed to a phase without the user asking
+
+**Decision locking**
+- Whenever a significant architectural, technical, or approach decision is made during a phase, write it to the `## Decisions Log` table in `project-state.md` in Contextium immediately.
+- A decision qualifies if it: picks a technology, sets an API contract, defines a data model, or establishes a pattern that future phases will depend on
+- Decisions in the log are **locked** — do not re-debate them in future sessions. If the user wants to revisit a decision, they must explicitly say so; only then remove or update the entry
+- Never ask the user's permission to log a decision — just do it silently and mention it in the phase summary
+
+**Tackling a new feature or phase**
+- When the user is ready to start work on a new feature or area of the project:
+  1. Update `## Current Position` in `project-state.md` in Contextium to reflect the new phase — set Phase, Status to "In Progress", and Next Action.
+  2. Ask: "Would you like to run a research phase on this first?" — if a research agent exists, use it; otherwise offer to create one
+  3. Ask: "Would you like a phased plan for this?" — if a planner agent exists, use it; otherwise offer to create one
+- If the user says no to both, continue directly using existing agents — no extra setup needed
+- Treat each new feature as its own mini-project using 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. Update `project-state.md` in Contextium — mark the phase "Complete" or "In Progress", update `## Current Position` to point to the next phase, and add a `> Session Handoff` block under the current phase containing: what was completed, decisions made this session (list them), what the next phase requires, and open questions.
+  2. Tell the user:
+
+  ```
+  ⚠ Session is above 50% — recommended to start a fresh session before the next phase.
+
+  Project state has been saved to your Contextium library.
+  Run /ium:resume-project to pick up exactly where you left off.
+  ```
+
+- If usage is **below 50%**, confirm the phase is complete, update `## Current Position` to the next phase, and ask if the user is ready to move on
+- Never skip this check at phase end — even if the user seems eager to continue
+
+**Multi-project rule**
+- Only one `project-state.md` should ever exist per context library. If a user has multiple projects, each project must have its own dedicated library — never mix two projects' state into one library.
+- If a second `project-state.md` would need to be created in the same library, stop and ask the user to either use a different library or create a new one for this project.
+
+**Project completion — convert to product description**
+- When all phases in `project-state.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 state into a Product Description document?"
+  2. If yes: rewrite the content in Contextium as a clean Product Description — summarise what was built, the decisions made (draw from the Decisions Log), the architecture or approach used, and outcomes. Remove phase status markers and the Decisions Log table. Title it "[Project Name] — Product Description". This document serves as a reference for future projects.
+  3. If no: leave the state file 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,127 @@
+---
+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>