forge-cc 0.1.40 → 1.0.0

package/skills/forge-triage.md

@@ -1,133 +1,179 @@
-# /forge:triage — Brain Dump to Linear Projects
-
-Turn sticky notes, rambling thoughts, and unstructured ideas into organized Linear projects. Paste anything — bullet points, paragraphs, stream of consciousness — and this skill extracts distinct projects, deduplicates against your existing Linear backlog, and creates them after your confirmation.
-
-## Instructions
-
-Follow these steps exactly. Do not skip confirmation.
-
-### Step 1 — Collect Input
-
-If the user has already provided text (ideas, notes, brain dump) in the same message as invoking this skill, use that as input. Otherwise, prompt:
-
-> Paste your ideas, sticky notes, or brain dump below. Any format works — bullet points, paragraphs, stream of consciousness. I'll extract the projects from whatever you give me.
-
-Wait for the user's input before continuing. Do not proceed with an empty input.
-
-If the input is extremely short or vague (fewer than 5 words with no actionable idea), ask:
-
-> That's a bit thin. Can you expand on what you're thinking? Even a sentence or two per idea helps me create better project descriptions.
-
-### Step 2 — Extract Projects
-
-Parse the input to identify distinct project ideas. For each idea, determine:
-
-- **Name**: Short, descriptive project name (2-5 words, title case)
-- **Description**: 1-2 sentence summary capturing the core intent
-- **Priority**: High / Medium / Low based on urgency signals in the text (words like "urgent", "ASAP", "critical", "soon" = High; "eventually", "someday", "nice to have" = Low; everything else = Medium)
-
-Rules for extraction:
-- Group related ideas into a single project. If someone mentions "mobile app redesign" and "fix the mobile nav", that is one project, not two.
-- If an idea is extremely vague (e.g., "maybe something with AI"), still extract it but flag it for clarification in Step 4.
-- For a single idea, create one project. For 10+ ideas, create as many projects as are genuinely distinct — do not artificially limit or pad.
-- Do not invent projects that were not in the input. Only extract what is there.
-
-### Step 3 — Deduplicate Against Linear
-
-Fetch existing projects from Linear:
-
-```
-Use mcp__linear__list_projects to get all existing projects.
-```
-
-For each extracted project, compare its name and description against existing projects. A project is a potential duplicate if:
-- The name is very similar (e.g., "Mobile Redesign" vs "Mobile App Redesign")
-- The description covers the same scope
-
-Mark duplicates with status `DUPLICATE` and reference the existing project name. Mark new projects with status `NEW`.
-
-If `mcp__linear__list_projects` fails (auth issue, Linear not configured), warn the user:
-
-> Could not connect to Linear to check for duplicates. Make sure your Linear MCP tools are configured. I'll proceed without dedup — you can review for duplicates manually.
-
-Then skip dedup and mark all projects as `NEW`.
-
-### Step 4 — Present for Confirmation
-
-Show the user a formatted list:
-
-```
-## Extracted Projects (N total)
-
-1. **Project Name** — Description
-   Priority: High | Status: NEW
-
-2. **Project Name** — Description
-   Priority: Medium | Status: DUPLICATE of "Existing Project Name"
-
-3. **Project Name** — Description
-   Priority: Low | Status: NEW | NOTE: This idea was vague — confirm or clarify?
-```
-
-Then ask:
-
-> Review the list above. You can:
-> - **Confirm all** — I'll create the NEW ones in Linear
-> - **Remove items** — tell me which numbers to skip (e.g., "remove 2, 5")
-> - **Edit items** — tell me what to change (e.g., "rename 3 to X" or "change 1 priority to Low")
-> - **Clarify** — expand on any flagged vague ideas
->
-> What would you like to do?
-
-Wait for the user's response. Apply any edits, removals, or clarifications. If the user says "confirm" or similar affirmative, proceed to Step 5. If they make changes, show the updated list and confirm again.
-
-### Step 5 — Create in Linear
-
-First, get the team ID (you only need to do this once):
-
-```
-Use mcp__linear__list_teams to get available teams.
-```
-
-If there is only one team, use it automatically. If there are multiple teams, ask the user which team to use.
-
-For each confirmed NEW project (skip items marked DUPLICATE that the user did not override):
-
-```
-Use mcp__linear__create_project with:
-  - name: the project name
-  - description: the project description
-  - state: "backlog"
-```
-
-If a project creation fails, report the error and continue with the remaining projects. Do not abort the entire batch for a single failure.
-
-After all projects are created, print a summary:
-
-```
-## Created N projects in Linear
-
-- **Project Name** — created successfully
-- **Project Name** — created successfully
-- **Project Name** — FAILED: [error message]
-
-Skipped M duplicates.
-```
-
-### Step 6 — Suggest Next Steps
-
-After creation, print:
-
-> **Next steps:**
-> - Run `/forge:spec` on any of these projects to create a detailed PRD with milestones
-> - Run `/forge:triage` again to add more ideas
-> - Open Linear to review and organize your new projects
-
-## Edge Cases
-
-- **Empty input**: Prompt the user to provide input. Do not create empty projects.
-- **Single idea**: Create one project. The workflow still applies (confirm before creating).
-- **10+ ideas**: Process all of them. Group aggressively to avoid near-duplicates.
-- **All duplicates**: Report that all ideas already exist in Linear. Suggest reviewing existing projects.
-- **Linear auth fails**: Warn the user, skip dedup, but still attempt creation. If creation also fails, provide manual instructions.
-- **Vague ideas**: Extract them with a clarification flag. Let the user decide whether to keep, clarify, or remove.
+# /forge:triage — Brain Dump to Linear Projects
+
+Turn sticky notes, rambling thoughts, and unstructured ideas into organized Linear projects. Paste anything — bullet points, paragraphs, stream of consciousness — and this skill extracts distinct projects, deduplicates against your existing Linear backlog, and creates them after your confirmation.
+
+**This skill uses Linear MCP tools directly** (`mcp__linear__*`) for all Linear operations. Unlike `/forge:go` and `/forge:spec` (which call forge CLI commands), triage is a conversational skill that requires interactive feedback at every step — direct MCP tool access is the correct pattern here.
+
+## Prerequisites
+
+This skill requires **Linear MCP tools** to be configured in your Claude environment. If the tools are not available, Step 0 will detect this and provide setup instructions. The required tools are:
+
+- `mcp__linear__list_projects` — fetch existing projects for dedup
+- `mcp__linear__list_teams` — resolve team for project creation
+- `mcp__linear__create_project` — create confirmed projects
+
+## Instructions
+
+Follow these steps exactly. Do not skip confirmation.
+
+### Step 0 — Resolve Team Configuration
+
+Read `.forge.json` from the project root. Check for the `linearTeam` field:
+
+- **If `linearTeam` is set** (non-empty string): store it as the configured team key. This will be used to auto-resolve the team in Step 5 and to scope project listing in Step 3.
+- **If `linearTeam` is empty or `.forge.json` does not exist**: no team is pre-configured. The skill will prompt for team selection in Step 5 if needed.
+
+This check is silent — do not print output unless there is an error reading the config.
+
+### Step 1 — Collect Input
+
+If the user has already provided text (ideas, notes, brain dump) in the same message as invoking this skill, use that as input. Otherwise, prompt:
+
+> Paste your ideas, sticky notes, or brain dump below. Any format works — bullet points, paragraphs, stream of consciousness. I'll extract the projects from whatever you give me.
+
+Wait for the user's input before continuing. Do not proceed with an empty input.
+
+If the input is extremely short or vague (fewer than 5 words with no actionable idea), ask:
+
+> That's a bit thin. Can you expand on what you're thinking? Even a sentence or two per idea helps me create better project descriptions.
+
+### Step 2 — Extract Projects
+
+Parse the input to identify distinct project ideas. For each idea, determine:
+
+- **Name**: Short, descriptive project name (2-5 words, title case)
+- **Description**: 1-2 sentence summary capturing the core intent
+- **Priority**: High / Medium / Low based on urgency signals in the text (words like "urgent", "ASAP", "critical", "soon" = High; "eventually", "someday", "nice to have" = Low; everything else = Medium)
+
+Rules for extraction:
+- Group related ideas into a single project. If someone mentions "mobile app redesign" and "fix the mobile nav", that is one project, not two.
+- If an idea is extremely vague (e.g., "maybe something with AI"), still extract it but flag it for clarification in Step 4.
+- For a single idea, create one project. For 10+ ideas, create as many projects as are genuinely distinct — do not artificially limit or pad.
+- Do not invent projects that were not in the input. Only extract what is there.
+
+### Step 3 — Deduplicate Against Linear
+
+Fetch existing projects from Linear, scoped to the configured team:
+
+```
+Use mcp__linear__list_projects to get existing projects.
+```
+
+If a `linearTeam` was resolved in Step 0, filter the returned projects to those belonging to the configured team. This prevents false duplicate matches against projects from other teams.
+
+For each extracted project, compare its name and description against existing projects. A project is a potential duplicate if:
+- The name is very similar (e.g., "Mobile Redesign" vs "Mobile App Redesign")
+- The description covers the same scope
+
+Mark duplicates with status `DUPLICATE` and reference the existing project name. Mark new projects with status `NEW`.
+
+If `mcp__linear__list_projects` fails (auth issue, Linear not configured, MCP tools unavailable), warn the user:
+
+> Could not connect to Linear to check for duplicates. Make sure your Linear MCP tools are configured in your Claude environment (see [Linear MCP setup docs](https://linear.app/docs)). I'll proceed without dedup — you can review for duplicates manually.
+
+Then skip dedup and mark all projects as `NEW`.
+
+### Step 4 — Present for Confirmation
+
+Show the user a formatted list:
+
+```
+## Extracted Projects (N total)
+
+1. **Project Name** — Description
+   Priority: High | Status: NEW
+
+2. **Project Name** — Description
+   Priority: Medium | Status: DUPLICATE of "Existing Project Name"
+
+3. **Project Name** — Description
+   Priority: Low | Status: NEW | NOTE: This idea was vague — confirm or clarify?
+```
+
+Then ask:
+
+> Review the list above. You can:
+> - **Confirm all** — I'll create the NEW ones in Linear
+> - **Remove items** — tell me which numbers to skip (e.g., "remove 2, 5")
+> - **Edit items** — tell me what to change (e.g., "rename 3 to X" or "change 1 priority to Low")
+> - **Clarify** — expand on any flagged vague ideas
+>
+> What would you like to do?
+
+Wait for the user's response. Apply any edits, removals, or clarifications. If the user says "confirm" or similar affirmative, proceed to Step 5. If they make changes, show the updated list and confirm again.
+
+### Step 5 — Create in Linear
+
+**Resolve the team:**
+
+If `linearTeam` was set in Step 0, resolve it to a team ID:
+
+```
+Use mcp__linear__list_teams to get available teams.
+```
+
+Match the configured `linearTeam` value against the returned teams by key or name. If a match is found, use that team automatically. If no match is found, warn:
+
+> The configured team "{linearTeam}" was not found in Linear. Available teams are listed below — pick one, or update `linearTeam` in `.forge.json`.
+
+Then present the available teams for selection.
+
+If `linearTeam` was NOT configured in Step 0:
+
+```
+Use mcp__linear__list_teams to get available teams.
+```
+
+If there is only one team, use it automatically. If there are multiple teams, ask the user which team to use.
+
+**Create projects:**
+
+For each confirmed NEW project (skip items marked DUPLICATE that the user did not override):
+
+```
+Use mcp__linear__create_project with:
+  - name: the project name
+  - description: the project description
+  - teamIds: [the resolved team ID]
+  - state: "backlog"
+```
+
+If a project creation fails, report the error and continue with the remaining projects. Do not abort the entire batch for a single failure.
+
+If ALL project creations fail (e.g., auth expired, MCP tools not responding), print:
+
+> Linear project creation failed. Check that your Linear MCP tools are configured and your API key is valid. You can create these projects manually in Linear:
+>
+> {list each project name and description}
+
+After all projects are created, print a summary:
+
+```
+## Created N projects in Linear
+
+- **Project Name** — created successfully
+- **Project Name** — created successfully
+- **Project Name** — FAILED: [error message]
+
+Skipped M duplicates.
+```
+
+### Step 6 — Suggest Next Steps
+
+After creation, print:
+
+> **Next steps:**
+> - Run `/forge:spec` on any of these projects to create a detailed PRD with milestones
+> - Run `/forge:triage` again to add more ideas
+> - Open Linear to review and organize your new projects
+
+## Edge Cases
+
+- **Empty input**: Prompt the user to provide input. Do not create empty projects.
+- **Single idea**: Create one project. The workflow still applies (confirm before creating).
+- **10+ ideas**: Process all of them. Group aggressively to avoid near-duplicates.
+- **All duplicates**: Report that all ideas already exist in Linear. Suggest reviewing existing projects.
+- **Linear MCP tools not configured**: Warn the user with setup instructions at the first point of failure (Step 3 or Step 5). Still extract and present projects — the user can create them manually.
+- **Linear auth fails mid-flow**: If dedup succeeds (Step 3) but creation fails (Step 5), print the project list in a copy-friendly format so the user can create them manually.
+- **Vague ideas**: Extract them with a clarification flag. Let the user decide whether to keep, clarify, or remove.
+- **Multiple teams with no config**: If `linearTeam` is not set in `.forge.json` and multiple teams exist, present a team picker. Suggest the user run `/forge:setup` or set `linearTeam` in `.forge.json` for future runs.

package/skills/forge-update.md

@@ -1,93 +1,87 @@
-# /forge:update — Update Forge to Latest Version
-
-Check for updates and install the latest version of forge-cc.
-
-## Instructions
-
-### Step 1 — Check Versions
-
-Run these commands to get version info:
-
-```bash
-# Current installed version
-forge --version
-
-# Latest available version
-npm view forge-cc version
-```
-
-Parse both versions. If the command fails, handle gracefully:
-- If `forge` is not found: print "forge-cc is not installed globally. Install with: `npm install -g forge-cc`"
-- If npm view fails (offline): print "Could not reach npm registry. Check your internet connection."
-
-### Step 2 — Compare and Report
-
-Print the version status:
-
-```
-## Forge Version Check
-
-**Installed:** v{current}
-**Latest:** v{latest}
-**Status:** {Up to date / Update available}
-```
-
-If already up to date, stop here with: "You're on the latest version."
-
-### Step 3 — Update
-
-If an update is available, run:
-
-```bash
-npm install -g forge-cc@latest
-```
-
-This does two things automatically:
-1. Installs the new version globally
-2. The `postinstall` hook runs `forge setup --skills-only`, which syncs all skills to `~/.claude/commands/forge/`
-
-Verify the update succeeded:
-
-```bash
-forge --version
-```
-
-If the version matches the latest, the update is complete. If it doesn't match, check if the user needs to restart their terminal or if there's a local `node_modules` shadowing the global install.
-
-### Step 4 — Verify Skills Synced
-
-Confirm skills were updated by listing the target directory:
-
-```bash
-ls ~/.claude/commands/forge/
-```
-
-If the directory is empty or missing, the postinstall hook may have failed silently. Run the manual fallback:
-
-```bash
-forge setup --skills-only
-```
-
-### Step 5 — Post-Update Check
-
-After updating, check if the current project's forge files need refreshing:
-
-1. Check if `.forge.json` exists in the current directory
-2. If it does (this is a forge project), suggest: "Run `/forge:setup` with Refresh mode to update project files to the latest templates."
-3. If it doesn't, just confirm the update.
-
-Print final summary:
-
-```
-## Update Complete
-
-**Previous:** v{old}
-**Current:** v{new}
-**Skills:** Synced to ~/.claude/commands/forge/
-
-{If forge project: "Consider running `/forge:setup` (Refresh) to update project files."}
-```
-
----
-
-Do NOT stage, commit, or push anything. This skill only manages the npm package.
+# /forge:update — Update Forge to Latest Version
+
+Check for updates and install the latest version of forge-cc.
+
+## Instructions
+
+### Step 1 — Check Versions
+
+Run the forge update CLI to check for a newer version:
+
+```bash
+npx forge update
+```
+
+Also get the exact installed version:
+
+```bash
+npx forge --version
+```
+
+If `forge` is not found, print: "forge-cc is not installed. Install with: `npm install -g forge-cc`"
+
+### Step 2 — Compare and Report
+
+Print the version status:
+
+```
+## Forge Version Check
+
+**Installed:** v{current}
+**Latest:** v{latest}
+**Status:** {Up to date / Update available}
+```
+
+If already up to date, stop here with: "You're on the latest version."
+
+### Step 3 — Update
+
+If an update is available, run:
+
+```bash
+npm install -g forge-cc@latest
+```
+
+The `postinstall` hook automatically runs `forge setup --skills-only` to sync all skills to `~/.claude/commands/forge/`.
+
+Verify the update succeeded:
+
+```bash
+npx forge --version
+```
+
+If the version matches the latest, the update is complete. If not, check if the user needs to restart their terminal or if a local `node_modules` is shadowing the global install.
+
+### Step 4 — Verify Skills Synced
+
+Confirm skills were updated:
+
+```bash
+ls ~/.claude/commands/forge/
+```
+
+If the directory is empty or missing, the postinstall hook may have failed. Run the manual fallback:
+
+```bash
+npx forge setup --skills-only
+```
+
+### Step 5 — Post-Update Check
+
+If `.forge.json` exists in the current directory, suggest: "Run `/forge:setup` with Refresh mode to update project files to the latest templates."
+
+Print final summary:
+
+```
+## Update Complete
+
+**Previous:** v{old}
+**Current:** v{new}
+**Skills:** Synced to ~/.claude/commands/forge/
+
+{If forge project: "Consider running `/forge:setup` (Refresh) to update project files."}
+```
+
+---
+
+Do NOT stage, commit, or push anything. This skill only manages the npm package.