@contextium/cli 1.0.21 → 1.0.22

package/skills/ium/new-project.legacy.md

@@ -58,6 +58,53 @@ 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:
 
@@ -105,13 +152,11 @@ Based on the project description and the analysis, build a setup plan. Think thr
 
 **Libraries:** What distinct knowledge areas did the user mention? Each major topic or type of content that needs to be stored separately should be its own library. If an existing library already covers one of these, mark it for reuse.
 
-**Agents:** What kind of AI assistant roles would serve this project? Think about what tasks the user will perform — research, writing, analysis, Q&A, etc. If an existing agent fits, mark it for reuse.
+**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 content in this project? 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`).
-
-**Workflow:** Propose one workflow name that bundles everything together for quick loading.
+**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):
 
@@ -119,29 +164,32 @@ Present the plan in this format (omit any section that has nothing in it):
 
 Here's what I'll set up for you:
 
-**New libraries to create**
-- "Library Name" — reason why this is needed
+**Libraries**
 
-**Existing libraries to reuse**
-- "Library Name" — why it's relevant
+| Action | Name | Purpose |
+|--------|------|---------|
+| Create | "Library Name" | reason why this is needed |
+| Reuse  | "Library Name" | why it's relevant |
 
-**New agents to create**
-- "Agent Name" — what it will do for this project
+**Agents**
 
-**Existing agents to reuse**
-- "Agent Name" — why it fits
+| Action | Name | Purpose |
+|--------|------|---------|
+| Create | "Agent Name" | what it will do for this project |
+| Reuse  | "Agent Name" | why it fits |
 
-**New skills to create**
-- "Skill Name" — what knowledge it will hold
+**Skills**
 
-**Existing skills to reuse**
-- "Skill Name" — why it fits
+| Action | Name | Purpose |
+|--------|------|---------|
+| Create | "Skill Name" | what knowledge it will hold |
+| Reuse  | "Skill Name" | why it fits |
 
-**Tags to create**
-- `category:value` — why this label is useful
+**Tags**
 
-**Workflow**
-- "Workflow Name" — bundles everything above for quick loading
+| Tag | Purpose |
+|-----|---------|
+| `category:value` | why this label is useful |
 
 Shall I go ahead and create all of this?
 
@@ -150,11 +198,107 @@ 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="create_resources">
-Only create what the user confirmed. Create in this order: tag types → tags → libraries → skills → agents → workflow.
+Only create what the user confirmed across all steps. Create in this order: tag types → tags → libraries → skills → agents (including research and planner 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:**
@@ -162,7 +306,6 @@ Suppress all errors silently — if something fails, skip it quietly and note it
 contextium library create "<name>" --workspace <slug>
 contextium agent create "<name>" --workspace <slug>
 contextium skill create "<name>" --workspace <slug>
-contextium workflow create "<name>" --workspace <slug>
 contextium tag create "<value>" --type <type-slug> --workspace <slug>
 contextium tag-type create "<name>" --workspace <slug>
 ```
@@ -170,13 +313,60 @@ contextium tag-type create "<name>" --workspace <slug>
 **MCP:** use the corresponding create_* tools for each resource type.
 </step>
 
-<step name="load_workflow">
-After all resources are created, automatically load the workflow without asking the user. Run silently:
+<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 load "<workflow-name>" --workspace <slug> 2>/dev/null`
+**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.
 
-Do not tell the user to load it themselves — just load it as part of setup.
+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: activate the research agent — instruct it to begin researching based on the project description provided earlier. 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">
@@ -190,7 +380,7 @@ 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
+Workflow:    <name> — loaded and ready   (or "none" if skipped)
 ```
 
 If anything failed to create, add a single line at the end:
@@ -205,7 +395,64 @@ If anything failed to create, add a single line at the end:
 - 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 — 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>