@contextium/cli 1.0.30 → 1.0.31

package/dist/lib/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/lib/api-client.ts"],"names":[],"mappings":"AAAA,OAAc,EAAiB,kBAAkB,EAAE,MAAM,OAAO,CAAA;AAGhE,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,MAAuC;IA4DtE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB;IAI5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB;IAIzD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB;IAI1D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB;IAIxD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB;CAGtD"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/lib/api-client.ts"],"names":[],"mappings":"AAAA,OAAc,EAAiB,kBAAkB,EAAE,MAAM,OAAO,CAAA;AAGhE,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,MAAuC;IA0DtE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB;IAI5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB;IAIzD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB;IAI1D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB;IAIxD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB;CAGtD"}

package/dist/lib/api-client.js

@@ -38,8 +38,6 @@ export class ApiClient {
                         throw new Error(errorMsg || 'Insufficient permissions');
                     case 404:
                         throw new Error(errorMsg || 'Resource not found');
-                    case 423:
-                        throw new Error(errorMsg || 'A workspace audit is running. Writes are temporarily paused — try again in a few minutes.');
                     case 429:
                         throw new Error(errorMsg || 'Rate limit exceeded');
                     default:

package/dist/lib/api-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/lib/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/lib/api-client.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/skills/ium/new-project.md

@@ -0,0 +1,536 @@
+---
+name: ium:new-project
+description: Set up a new Contextium project — authenticate, pick a workspace, describe project, intelligently suggest and create libraries, agents, skills, tags, and a workflow. SUGGEST (proactively ask, don't auto-run) when the user seems to be starting a new project or exploring how to organise their AI context — for example: "I'm starting a new project", "I want to get organised with AI", "how do I get the most out of Claude for my project", "I want Claude to know about my project", "I want to set up AI properly for my work", "I need a way for AI to understand my codebase". In these cases ask: "Would you like to set up a Contextium project? I can create libraries, agents, and skills tailored to what you're building — so any AI in your workflow has the right context automatically." — then wait for confirmation. TRIGGER when user says things like: "set up Contextium", "start a new Contextium project", "create a new project in Contextium", "I want to use Contextium", "get started with Contextium", "initialise Contextium for my project", "configure Contextium for me", "connect my project to Contextium", "onboard to Contextium", "set up my Contextium workspace", "create libraries and agents for my project", "I'm new to Contextium help me get set up", "create a Contextium project from scratch", "set up everything in Contextium for me", "help me configure Contextium".
+allowed-tools:
+  - Bash
+  - mcp__contextium__list_workspaces
+  - mcp__contextium__create_context_library
+  - mcp__contextium__list_context_libraries
+  - mcp__contextium__create_agent
+  - mcp__contextium__list_agents
+  - mcp__contextium__create_skill
+  - mcp__contextium__list_skills
+  - mcp__contextium__create_workflow
+  - mcp__contextium__list_workflows
+  - mcp__contextium__list_tags
+  - mcp__contextium__list_tag_types
+  - mcp__contextium__create_tag
+  - mcp__contextium__create_tag_type
+  - AskUserQuestion
+  - WebFetch
+---
+
+<objective>
+Set up a new Contextium project intelligently — understand what the user is trying to do, quietly analyse the workspace for existing resources, then recommend exactly what to create (libraries, agents, skills, tags, workflow) with clear reasoning. Get confirmation before creating anything.
+</objective>
+
+<mode-detection>
+Run this once at the start, silently, to determine which mode to use for the entire session:
+
+```bash
+command -v contextium &>/dev/null && echo "cli" || echo "no-cli"
+```
+
+- If `cli`: use CLI commands throughout. Do not attempt MCP tools.
+- If `no-cli`: check if mcp__contextium__list_workspaces is available. If yes, use MCP tools throughout.
+- If neither: tell the user "Contextium doesn't appear to be installed. Install the CLI with `npm install -g @contextium/cli` or connect the MCP server, then re-run this." Stop here.
+
+Do not mention the mode to the user. Pick one path and stick with it.
+</mode-detection>
+
+<process>
+
+<step name="check_auth">
+**CLI only.** Run silently:
+```bash
+contextium whoami 2>/dev/null | grep -E "Token:|Name:" || echo "unauthenticated"
+```
+If token is expired or unauthenticated, tell the user: "Your Contextium session has expired — run `contextium login` in your terminal, then come back and re-run this." Stop here.
+
+MCP users are already authenticated via the server connection — skip this step.
+</step>
+
+<step name="select_workspace">
+**CLI:** run `contextium workspace list 2>/dev/null` silently, parse workspace names.
+**MCP:** call mcp__contextium__list_workspaces silently.
+
+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="codebase_scan_check">
+Silently check whether any library in the selected workspace contains codebase analysis documents from `/ium:scan-existing`. Look for files named `stack.md`, `architecture.md`, `structure.md`, `conventions.md`, `concerns.md` in any library.
+
+**CLI:** `contextium library list --workspace <slug> 2>/dev/null` then check file lists per library
+**MCP:** call mcp__contextium__list_context_libraries, then mcp__contextium__list_files for each
+
+If found, read `architecture.md` and `stack.md` silently to understand what already exists. Store this as `has_codebase_scan = true` and `codebase_library = <library name>`. This will be used later to pre-populate validated capabilities in the project state.
+
+If not found, set `has_codebase_scan = false` and continue.
+
+Do not mention this check to the user.
+</step>
+
+<step name="project_description">
+Ask the user this question exactly:
+
+"Tell me about your project — what are you trying to do, what topics are involved, and what kind of work will you be doing with this? The more detail you give me, the better I can set things up for you."
+
+Wait for their response. Store it as the project description. Do not proceed until you have a meaningful answer.
+</step>
+
+<step name="quiet_analysis">
+Silently fetch all existing workspace resources. Do not show raw output or errors. Show only these progress lines as you go:
+
+```
+Searching libraries...
+Searching agents...
+Searching skills...
+Searching tags...
+```
+
+**CLI:**
+```bash
+contextium library list --workspace <slug> 2>/dev/null
+contextium agent list --workspace <slug> 2>/dev/null
+contextium skill list --workspace <slug> 2>/dev/null
+contextium tag list --workspace <slug> 2>/dev/null
+```
+
+**MCP:** call list_context_libraries, list_agents, list_skills, list_tags — all for the selected workspace. Suppress any errors silently.
+
+After all four searches complete, output this line:
+```
+Creating Contextium setup plan...
+```
+
+Then analyse the results against the project description:
+- Which existing libraries (if any) are relevant to what the user described?
+- Which existing agents (if any) could serve this project?
+- Which existing skills (if any) are applicable?
+- Which existing tags/tag types (if any) relate to the topics mentioned?
+
+Internally categorise everything as: **reuse** (relevant, already exists) or **create** (needed, does not exist).
+</step>
+
+<step name="intelligent_plan">
+Based on the project description and the analysis, build a setup plan. Think through:
+
+**Libraries:** Create exactly ONE library per project. All planning documents, technical documents, research, and project state files go into this single library. Give it a clear name (e.g. "Contextium Desktop App") and a one-sentence description of what the project is. Do not split a project across multiple libraries. If an existing library already covers this project, mark it for reuse instead of creating a new one.
+
+**Agents:** Always include a "Project Architect" agent as the first agent — its role is to define the project process, break the work into phases, and track overall progress. Write its system prompt to be specific to this project's domain and goals. Then think about what other AI assistant roles would serve this project based on what the user described. If an existing agent fits one of the additional roles, mark it for reuse.
+
+**Skills:** What reusable knowledge blocks would help agents working on this project? Think about domain-specific guidelines, reference material, or persistent context the agent needs. If an existing skill fits, mark it for reuse.
+
+**Tags:** What topic or category labels would make sense for organising **files within context libraries** for this project? Tags apply to library files only — never suggest tags for agents or skills. Look for existing tag types that match. If none exist, suggest new ones. Think in terms of tag categories (e.g. `topic`, `source`, `status`) and the specific tag values within them (e.g. `topic:space-travel`, `topic:rocket-engineering`).
+
+Present the plan in this format (omit any section that has nothing in it):
+
+---
+
+Here's what I'll set up for you:
+
+**Libraries**
+
+| Action | Name | Purpose |
+|--------|------|---------|
+| Create | "Library Name" | reason why this is needed |
+| Reuse  | "Library Name" | why it's relevant |
+
+**Agents**
+
+| Action | Name | Purpose |
+|--------|------|---------|
+| Create | "Agent Name" | what it will do for this project |
+| Reuse  | "Agent Name" | why it fits |
+
+**Skills**
+
+| Action | Name | Purpose |
+|--------|------|---------|
+| Create | "Skill Name" | what knowledge it will hold |
+| Reuse  | "Skill Name" | why it fits |
+
+**Tags**
+
+| Tag | Purpose |
+|-----|---------|
+| `category:value` | why this label is useful |
+
+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 state 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 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 State
+
+## Current Position
+**Phase:** Phase 1: [Name]
+**Status:** Not Started
+**Last Updated:** [today's date]
+**Next Action:** Begin Phase 1
+
+## Already Built
+> Capabilities confirmed by codebase scan — these do not need to be built.
+> _(Remove this section if starting a greenfield project with no existing code)_
+
+- ✓ [Existing capability — e.g. "Express API with JWT auth"] — `src/server.ts`
+- ✓ [Existing capability] — `src/`
+
+## Phases
+
+### Phase 1: [Name]
+**Status:** Not Started
+[Brief description of what this phase covers]
+
+### 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. Title the file `project-state.md`.
+
+**If `has_codebase_scan = true`:** populate the `## Already Built` section from the `architecture.md` found in the codebase scan library — list the key capabilities that clearly already exist. Only plan phases for what is **not** in the Already Built list. If starting greenfield, remove the Already Built section entirely.
+
+**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>
+
+<step name="regression_agent_question">
+Ask the user:
+
+"Would you like a regression testing agent for this project? It will write E2E tests alongside every new feature so nothing you've built ever breaks silently."
+
+Use AskUserQuestion:
+- "Yes, add a regression testing agent"
+- "No, skip"
+
+If yes:
+1. Add a "**[Project Name] Regression Tester**" agent to the creation plan. Its system prompt should:
+   - Know that every feature must include an E2E Playwright test as a required deliverable
+   - Know the test suite lives in `apps/web/e2e/` and tests run against `https://staging.contextium.io`
+   - Know the rule: a feature is not complete until its E2E test is written and the full regression suite passes on staging
+   - Be instructed to write focused, realistic tests using existing page selectors and routes — not generic placeholder tests
+2. Store as `regression_agent_planned = true`.
+
+3. Check if Playwright is already installed by running silently:
+   ```bash
+   cd apps/web && npx playwright --version 2>/dev/null | grep -q "Version" && echo "installed" || echo "not-installed"
+   ```
+
+   If not installed, ask:
+
+   "Playwright is required to run E2E tests. Would you like me to install it now?"
+
+   Use AskUserQuestion:
+   - "Yes, install Playwright"
+   - "No, I'll install it later"
+
+   If yes — install silently:
+   ```bash
+   cd apps/web && npm install -D @playwright/test && npx playwright install chromium
+   ```
+   Show `✓ Playwright installed` when done.
+
+   If no — store `playwright_install_pending = true` and add a note to the final summary:
+   `⚠ Playwright not installed — run the following before running E2E tests:`
+   `  cd apps/web && npm install -D @playwright/test && npx playwright install chromium`
+
+If no: set `regression_agent_planned = false` and continue.
+</step>
+
+<step name="create_resources">
+Only create what the user confirmed across all steps. Create in this order: tag types → tags → libraries → skills → agents (including research, planner, and regression 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 state file in Contextium after all other resources are created:
+
+**CLI:**
+```bash
+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 state content.
+
+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.
+
+**CLI commands:**
+```bash
+contextium library create "<name>" --description "<description>" --workspace <slug>
+contextium agent create "<name>" --workspace <slug>
+contextium skill create "<name>" --workspace <slug>
+contextium tag create "<value>" --type <type-slug> --workspace <slug>
+contextium tag-type create "<name>" --workspace <slug>
+```
+
+**MCP:** use the corresponding create_* tools for each resource type.
+</step>
+
+<step name="workflow_prompt">
+After all other resources are created, ask the user:
+
+"Would you like me to create a workflow to bundle everything together for quick loading? If yes, what would you like to call it?"
+
+Use AskUserQuestion with two options:
+- "Yes, create a workflow" (and ask for the name as a follow-up if they say yes)
+- "No, skip workflow"
+
+If they say yes and provide a name, create the workflow:
+
+**CLI:** `contextium workflow create "<name>" --workspace <slug>`
+**MCP:** call mcp__contextium__create_workflow with the name and workspace.
+
+Then automatically load it:
+
+**CLI:** `contextium workflow load "<name>" --workspace <slug> 2>/dev/null`
+**MCP:** call mcp__contextium__load_workflow with the workflow name and workspace.
+
+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:
+
+1. Ask the user:
+
+   "Do you have any reference URLs you'd like me to use as a starting point for research? Paste any links — documentation, competitor sites, articles, specs — and I'll include them."
+
+   Use AskUserQuestion:
+   - "Yes, here are my URLs: [user types them]"
+   - "No, start without references"
+
+   Store any URLs provided as `research_reference_urls`. If the user provides URLs, fetch each one with WebFetch before beginning research, and include the fetched content as source material for the research agent.
+
+2. Activate the research agent — instruct it to begin researching based on the project description provided earlier, incorporating any reference URLs fetched in the previous step. 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-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>
+
+<step name="summary">
+Show a clean final summary:
+
+```
+✓ Project ready
+
+Workspace:   <name>
+Libraries:   <list — new + reused>
+Agents:      <list — new + reused, or none>
+Skills:      <list — new + reused, or none>
+Tags:        <list, or none>
+Workflow:    <name> — loaded and ready   (or "none" if skipped)
+```
+
+If anything failed to create, add a single line at the end:
+`⚠ Could not create: <list of names> — you can add these manually.`
+</step>
+
+</process>
+
+<rules>
+- Never say "the wizard", "Contextium would like to know", or "the next step is"
+- Never show raw bash output, API responses, or IDs to the user
+- Run all checks and fetches silently — only surface progress labels and the final plan
+- Only ask questions when genuinely needed — the description step and the confirmation step
+- Do not ask the user what to create — figure it out from the description, then ask them to confirm
+- Always create a "Project Architect" agent first, regardless of what the user described — tailor its system prompt to the specific project domain and goals
+- If a resource already exists and is relevant, always prefer reuse over creating a duplicate
+- 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 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
+
+**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 — output documents**
+- When all phases in `project-state.md` are marked "Complete", automatically trigger the following:
+  1. Congratulate the user, then ask: "All phases are complete — great work! Would you like me to generate any of the following documents from your project state?"
+
+     Present these options (allow multiple selections):
+     - **Product Feature Document** — a clear summary of what was built, the capabilities delivered, and the decisions made. Aimed at internal teams and stakeholders.
+     - **Product Requirements Document (PRD)** — a structured requirements doc covering goals, user needs, scope, and feature definitions. Useful for future development or handoffs.
+     - **Product Marketing Document** — a sales-oriented document that frames the product in terms of value, audience, pain points solved, and key differentiators. Aimed at external communication and go-to-market use.
+     - **None, leave as-is**
+
+  2. For each document type selected, check the current workspace for an existing agent that can produce it:
+     - Look for agents with names or system prompts suggesting they handle product writing, technical writing, marketing copy, or PRD generation
+     - If a suitable agent exists: activate it and instruct it to generate the document using the project state, Decisions Log, and phase history
+     - If no suitable agent exists: offer to create one — e.g. "I don't see a product writing agent in this workspace. Shall I create a **Product Writer** agent to generate this for you?" — wait for confirmation before creating
+
+  3. For each document generated:
+     - Save it to the project library in Contextium using a clear filename:
+       - `product-feature-doc.md` for the Feature Document
+       - `prd.md` for the PRD
+       - `product-marketing-doc.md` for the Marketing Document
+     - Show `✓ Saved "[filename]" to [library name]` when done
+
+  4. If any new agents were created to generate documents, ask: "Would you like to add these agents to your workflow so they're available in future sessions?" — if yes, add them to the workflow using the CLI or MCP tools.
+
+  5. After all selected documents are generated, leave `project-state.md` intact — do not delete or overwrite it.
+
+- Never generate documents automatically without asking — always get confirmation first
+- If the user selects "None, leave as-is": congratulate them and close out the session
+</ongoing-project-rules>