@contextium/cli 1.0.14 → 1.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextium/cli",
-  "version": "1.0.14",
+  "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/new-project.md

@@ -202,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"
@@ -210,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>
@@ -238,25 +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.
 
-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.
+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.
 
@@ -323,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>
@@ -364,16 +383,24 @@ 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
@@ -383,28 +410,27 @@ These rules apply for the duration of the project, after setup is complete.
 **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:
+  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.
 
-  A handoff note has been saved to your project plan.
+  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%**, simply confirm the phase is complete and ask if the user is ready to move to the next phase
+- 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
 
-**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
+**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-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
+- 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

@@ -34,72 +34,66 @@ Load the chosen workflow silently:
 **MCP:** call mcp__contextium__load_workflow
 </step>
 
-<step name="find_project_plan">
-Check for the project plan in this order:
+<step name="find_project_state">
+Contextium is the source of truth. Always read from there first.
 
-**1. Local first** — check for `.ium-planning/project-plan.md` in the current directory:
+**1. Contextium first** — search the loaded workflow's libraries for `project-state.md`:
 
-```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`
+**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 in Contextium, fetch the full content:
+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
 
-Then write it to `.ium-planning/project-plan.md` locally so future sessions have the local copy:
+**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.
 
-```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?"
+**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_handoff">
-Read the project plan and identify:
+<step name="parse_state">
+Read the project state file and extract:
 
-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
+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"
+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 phases:
+Completed:
   ✓ Phase 1: [Name]
   ✓ Phase 2: [Name]
 
-Current phase:
+Current:
   → Phase 3: [Name] — In Progress
+  Next action: [from Current Position]
 
 Last session notes:
-  [Handoff note content]
+  [Handoff note content, or phase description if no handoff]
 
 Up next:
-  [What the handoff says needs to happen next]
+  [What the handoff says needs to happen]
 
-Remaining phases:
+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>
 
@@ -113,21 +107,21 @@ Use AskUserQuestion:
 - "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 "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-plan.md`.
+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 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
+- 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>