Sign In

@contextium/cli

Package Overview
Dependencies
Maintainers
2
Versions
108
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@contextium/cli - npm Package Compare versions

Comparing version
1.0.14
 to
1.0.15
+1
-1
package.json
{
"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",

@@ -5,0 +5,0 @@ "keywords": [

+26
-0
skills/ium/contextium.md

@@ -52,2 +52,28 @@ ---

## 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

@@ -54,0 +80,0 @@ 

+66
-40
skills/ium/new-project.md

@@ -205,3 +205,3 @@ ---

"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."

@@ -214,12 +214,20 @@ Use AskUserQuestion:

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

@@ -229,6 +237,25 @@ [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.

@@ -244,22 +271,14 @@ </step>

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:
Show `✓ Created project state "project-state.md"` when done.
```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.

@@ -330,3 +349,3 @@

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.

@@ -372,13 +391,21 @@ If no: continue to summary.

**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
- Seeds are NOT immediate work — never promote a seed to a phase without the user asking
**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
**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**

@@ -392,5 +419,4 @@ - 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

- 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:

@@ -400,19 +426,19 @@ ```

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>
+35
-41
skills/ium/resume-project.md

@@ -37,42 +37,30 @@ ---

<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
```
**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 locally, use it. Show `→ Using local project plan (.ium-planning/project-plan.md)` and skip the Contextium lookup.
If found, fetch the full content:
**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:
**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)

@@ -84,22 +72,28 @@ Present a clear resumption brief:

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.

@@ -118,7 +112,7 @@ </step>

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>

@@ -130,8 +124,8 @@

- 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>