forge-cc 1.0.2 → 2.0.0

package/skills/forge-spec.md

@@ -1,367 +0,0 @@
-# /forge:spec — Linear Project to PRD with Milestones
-
-Turn a Linear project into a detailed PRD with milestones and issues. This skill scans the codebase, conducts an adaptive interview, generates a PRD, and syncs the plan back to Linear.
-
-## Instructions
-
-Follow these steps exactly. The interview is adaptive — lead with recommendations, not blank-slate questions.
-
-### Step 1 — Select Linear Project
-
-Fetch incomplete projects from Linear:
-
-```
-Use mcp__linear__list_projects to get all existing projects.
-```
-
-Filter to projects in "Backlog" state (these are triaged but not yet specced). Present them as a numbered list:
-
-```
-## Projects Ready for Spec
-
-1. **Project Name** — description
-2. **Project Name** — description
-```
-
-Then ask:
-
-> Which project would you like to spec? Pick a number, or type a project name.
-
-If no Backlog projects exist, say:
-
-> No projects in Backlog state. Run `/forge:triage` first to create projects from your ideas, or create one directly in Linear.
-
-Wait for the user's selection before continuing.
-
-### Step 2 — Scan the Codebase
-
-Run 3 parallel codebase scan agents using the Task tool (subagent_type: Explore):
-
-**Agent 1 — Structure Scanner:**
-```
-Use Glob and Read tools to scan for: package.json, tsconfig.json, .env*, config files, key directories (src/, app/, pages/, lib/).
-Report: framework, language, dependencies, project structure, build tools.
-```
-
-**Agent 2 — Routes/UI Scanner:**
-```
-Use Glob and Grep tools to scan for: route files, pages, layouts, navigation components, route definitions.
-Look in common locations: src/app/, src/pages/, src/routes/, app/, pages/.
-Grep for route patterns (e.g., "createBrowserRouter", "Route", "router.", "app.get", "app.post").
-Report: routing framework, page count, API route count, layout structure.
-```
-
-**Agent 3 — Data/APIs Scanner:**
-```
-Use Glob and Grep tools to scan for: API endpoints, database files (schema.prisma, migrations/, models/), env files (.env*), external service configs, ORM setup, SDK clients.
-Grep for patterns like "fetch(", "axios", "prisma.", "mongoose.", "createClient".
-Report: database type, API patterns, external integrations, auth setup.
-```
-
-Combine the results into a plain-text summary. Print a brief overview:
-
-```
-## Codebase Scan Complete
-
-- **Framework:** Next.js (TypeScript)
-- **Pages:** 12 | **API Routes:** 8
-- **Dependencies:** 24 | **DB Files:** 3
-- **Key Files:** src/lib/auth.ts, src/db/schema.prisma, ...
-```
-
-If the current working directory does not look like a project (no package.json, no src/), warn:
-
-> This directory doesn't look like a project root. Should I scan here, or provide a path to the project?
-
-### Step 3 — LLM-Driven Adaptive Interview
-
-You (the LLM) drive the interview directly. Track coverage mentally across the 5 sections. No TypeScript state tracking — you are the state tracker.
-
-The interview covers 5 sections:
-
-1. **Problem & Goals** — core problem, desired outcome, success criteria, impact/urgency, current workarounds, who feels the pain
-2. **User Stories** — primary users, user workflows step-by-step, secondary users, edge cases, permissions/roles, error states
-3. **Technical Approach** — architecture pattern, data model/schema, APIs/integrations, auth/security, performance requirements, error handling, existing code to leverage
-4. **Scope** — in scope boundaries, out of scope, sacred files/areas, constraints, future phases explicitly deferred
-5. **Milestones** — breakdown into chunks, dependencies between milestones, sizing (fits in one agent context?), verification criteria, delivery order, risk areas
-
-**Interview Loop — You Drive:**
-
-1. Start with a broad opening question for Problem & Goals, informed by scan results
-2. After each answer:
-   - Assess coverage gaps mentally (which topics are uncovered? which answers were vague?)
-   - Generate the next question based on: scan results, all prior Q&A, what's still ambiguous
-   - Probe deeper on vague or short answers — don't accept "TBD" or one-liners for important topics
-   - Move to the next section when the current one has thorough coverage
-   - Revisit earlier sections if later answers reveal new info
-3. Continue until all 5 sections have adequate coverage
-
-**Question Principles — Encode These:**
-
-- Ask about edge cases, error states, and "what could go wrong"
-- When the user mentions an integration, ask about auth, rate limits, failure modes
-- When the user describes a workflow, walk through it step-by-step
-- For milestones, actively challenge sizing — "is this too big for one context window?"
-- Don't ask yes/no questions — ask "how" and "what" questions that elicit detail
-- Circle back to earlier sections when new info surfaces
-- Follow interesting threads: if the user mentions migration, breaking changes, multiple user types, or external services, dig deeper
-
-**Stop Condition:**
-
-You determine you have enough detail for a thorough PRD across ALL sections, with no significant ambiguity remaining. Before transitioning to Step 4, print a coverage summary showing the final state of each section.
-
-**Early Exit:**
-
-If the user says "stop", "that's enough", "skip", or "generate it" at any time, respect that and move to Step 4 with what you have.
-
-**Milestone Sizing Constraint (Hard Rule):**
-
-Each milestone MUST be completable in one main agent context window. If a milestone requires more than ~4 agents across 2-3 waves, split it. This is non-negotiable — large milestones cause context overflow and execution failures. When interviewing about milestones, actively recommend splitting any milestone that looks too large.
-
-**Milestone Dependencies (dependsOn):**
-
-During the milestones phase of the interview, ask about milestone dependencies using AskUserQuestion. For each milestone after the first, ask:
-
-- question: "Does Milestone {N} depend on any previous milestones?"
-- options:
-  - "No dependencies — can start immediately"
-  - "Depends on Milestone {N-1} (sequential)"
-  - "Depends on specific milestones (I'll specify)"
-
-If milestones have explicit dependencies, include `**dependsOn:** 1, 2` in the milestone section of the PRD. If no dependencies are specified, omit the field (backward compatible — treated as sequential).
-
-Independent milestones enable parallel execution via `/forge:go`, which creates separate worktrees for each parallel milestone.
-
-**Question Format:**
-
-Mix AskUserQuestion (for structured choices) and conversational questions (for open-ended probing):
-
-- **Use AskUserQuestion** when there are clear option sets (architecture choices, yes/no with detail, picking from scan-derived options). Provide 2-4 options plus "Other (I'll describe)".
-- **Use conversational questions** when probing for depth, asking "how" or "what" questions, or exploring topics that don't have predefined options.
-- **NEVER present questions as numbered text lists.** Each structured question gets its own AskUserQuestion call.
-- **Lead with recommendations.** Every question includes context from the codebase scan. Never ask a blank "what do you want to build?" question.
-
-**Progress Display:**
-
-After each answer, show a compact coverage status:
-
-```
-Progress: Problem & Goals [thorough] | User Stories [moderate] | Technical [thin] | Scope [none] | Milestones [none]
-```
-
-**Draft Updates:**
-
-- **Update the PRD draft every 2-3 answers.** Write to `.planning/prds/{project-slug}.md`. Tell the user:
-
-> Updated PRD draft at `.planning/prds/{slug}.md` — you can review it anytime.
-
-**Do NOT do this (anti-pattern):**
-
-```
-### Round N
-
-1. **[Section]** Question text?
-2. **[Section]** Question text?
-
-> Answer by number...
-```
-
-This numbered-text format is explicitly prohibited. Always use AskUserQuestion for structured choices.
-
-### Step 4 — Generate PRD
-
-Using all gathered interview answers and codebase scan results, generate the final PRD directly. The LLM synthesizes all interview data into the PRD — no external generator module needed.
-
-The PRD should follow this structure:
-
-```markdown
-# PRD: {Project Name}
-
-## Problem & Goals
-{Synthesized from interview answers}
-
-## User Stories
-{Structured user stories derived from interview}
-
-## Technical Approach
-{Stack decisions, architecture, constraints — informed by codebase scan}
-
-## Scope
-### In Scope
-{What will be built}
-
-### Out of Scope
-{Explicitly excluded items}
-
-### Sacred Files
-{Files/areas not to be touched}
-
-## Milestones
-
-### Milestone 1: {Name}
-**Goal:** {What this delivers}
-**Issues:**
-- [ ] Issue title — brief description
-- [ ] Issue title — brief description
-
-### Milestone 2: {Name}
-**dependsOn:** 1
-**Goal:** {What this delivers}
-...
-```
-
-**Milestone sizing check:** Before finalizing, review each milestone against the sizing constraint. Every milestone MUST fit in one agent context window (~4 agents across 2-3 waves max). If any milestone exceeds this, split it into smaller milestones before writing the final PRD. Set `maxContextWindowFit: true` on all milestones — if you cannot make a milestone fit, flag it as `maxContextWindowFit: false` and warn the user.
-
-**Test criteria guidance:** Test criteria are optional. Only include them when the milestone produces testable behavior. Verification commands (`npx tsc --noEmit`, `npx forge verify`) are always included automatically — test criteria are for additional functional checks beyond mechanical gates. When including test criteria, make them **functional**, not structural:
-- Good: "CLI `npx forge verify` runs and exits 0", "tsc compiles with no errors", "the new gate produces structured JSON output"
-- Bad: "All new source files must have corresponding test files", "Run npx forge verify --gate tests"
-
-Write the final PRD to `.planning/prds/{project-slug}.md`.
-
-After writing the PRD file, **execute BOTH steps below — do not skip either**:
-
-1. **Create status file:** Write `.planning/status/<slug>.json` with all milestones set to "pending". **You MUST include `linearProjectId` and `linearTeamId`** — these are the Linear project UUID and team UUID from the project selected in Step 1. Without `linearProjectId`, `/forge:go` cannot sync Linear issue or project state and will silently skip all Linear operations. Without `linearTeamId`, `forge linear-sync` silently skips all operations. Copy the exact IDs — do not omit these fields:
-   ```json
-   {
-     "project": "{project name}",
-     "slug": "{slug}",
-     "branch": "feat/{slug}",
-     "createdAt": "{today}",
-     "linearProjectId": "{Linear project UUID from Step 1}",
-     "linearTeamId": "{team UUID — resolved in Step 5, but placeholder here}",
-     "milestones": {
-       "1": { "status": "pending" },
-       "2": { "status": "pending" }
-     }
-   }
-   ```
-
-2. **Create feature branch:** `git checkout -b feat/{slug}`
-
-Tell the user:
-
-> Final PRD written to `.planning/prds/{slug}.md`.
-> Status file created at `.planning/status/{slug}.json`.
-> Feature branch `feat/{slug}` created.
-
-Present the full PRD in chat for review and ask:
-
-> Review the PRD above. You can:
-> - **Approve** — I'll create milestones and issues in Linear
-> - **Edit** — tell me what to change (e.g., "add a milestone for testing" or "remove the admin user story")
-> - **Regenerate** — start the interview over
->
-> What would you like to do?
-
-Wait for approval before continuing to Step 5.
-
-### Step 5 — Sync to Linear
-
-After the user approves the PRD, create milestones and issues in Linear.
-
-First, get the team ID:
-
-```
-Use mcp__linear__list_teams to get available teams.
-```
-
-If there is only one team, use it automatically. If multiple, ask the user which team.
-
-**Store the team ID** — it will be written to the status file after sync.
-
-For each milestone in the PRD:
-
-```
-Use mcp__linear__create_milestone with:
-  - projectId: the selected project's ID
-  - name: milestone name
-  - description: milestone goal
-```
-
-**Record the returned milestone ID** for each milestone.
-
-For each issue under that milestone:
-
-```
-Use mcp__linear__create_issue with:
-  - title: issue title
-  - description: issue description (from PRD)
-  - teamId: the team ID
-  - projectId: the project ID
-  - milestoneId: the milestone ID just created
-```
-
-**Record the returned issue IDs** for each milestone.
-
-**After all milestones and issues are created, do THREE things:**
-
-1. **Transition the project to "Planned":**
-
-```
-Use mcp__linear__update_project to set the project state to "planned".
-```
-
-**The project is a separate entity from its milestones and issues.** Creating milestones and issues does NOT automatically update the project state. You must explicitly call `mcp__linear__update_project`. Without this transition, `/forge:go` will find the project still in "Backlog" and the state machine will reject the "In Progress" transition.
-
-2. **Update the status file** at `.planning/status/<slug>.json` with the Linear IDs:
-
-```json
-{
-  "project": "{project name}",
-  "slug": "{slug}",
-  "branch": "feat/{slug}",
-  "createdAt": "{today}",
-  "linearProjectId": "{Linear project UUID from Step 1}",
-  "linearTeamId": "{team UUID from this step}",
-  "milestones": {
-    "1": { "status": "pending", "linearMilestoneId": "{id}", "linearIssueIds": ["{id1}", "{id2}"] },
-    "2": { "status": "pending", "linearMilestoneId": "{id}", "linearIssueIds": ["{id1}", "{id2}"] }
-  }
-}
-```
-
-**`linearTeamId` is MANDATORY.** Without it, `forge linear-sync` silently skips all operations. **`linearMilestoneId` and `linearIssueIds` per milestone are MANDATORY.** These enable `/forge:go` to transition issues as milestones are completed.
-
-3. **Print a summary:**
-
-```
-## Synced to Linear
-
-- **Project:** {name} (now "Planned")
-- **Milestones:** {N} created
-- **Issues:** {M} created across all milestones
-
-View in Linear: {project URL}
-```
-
-If any creation fails, report the error and continue with remaining items.
-
-### Step 6 — Handoff
-
-After sync, print the handoff prompt:
-
-```
-## Ready for Development
-
-PRD: `.planning/prds/{slug}.md`
-Status: `.planning/status/{slug}.json`
-Branch: `feat/{slug}`
-Linear: {project URL}
-
-**Next step:** Run `/forge:go` for one milestone at a time, or exit and run `npx forge run` to execute all milestones autonomously. The execution engine will:
-- Read the PRD and per-PRD status file
-- Spawn agent teams for each milestone
-- Verify each change with forge verification gates
-- Update status JSON and transition Linear issues automatically
-```
-
-**Note:** `/forge:go` now uses git worktrees for session isolation. Multiple users can run `/forge:go` on different milestones simultaneously without conflicts.
-
-## Edge Cases
-
-- **No Linear connection:** Warn the user. Still generate the PRD locally — skip the Linear sync steps.
-- **Empty codebase:** The interview still works — questions will be more open-ended without scan context. Note this to the user.
-- **User wants to spec a project not in Linear:** Allow it. Skip Step 1 project selection, ask for a project name, and create the Linear project in Step 5 before creating milestones.
-- **User provides info upfront:** If the user includes project details in the same message as `/forge:spec`, use that info to pre-fill interview answers and skip questions that are already answered.
-- **Very large codebase:** Scan agents may return truncated results. That's fine — the interview fills in gaps.
-- **Interrupted interview:** If the user stops mid-interview, save what you have to the PRD draft. They can resume by running `/forge:spec` again and selecting the same project.

package/skills/forge-triage.md

@@ -1,179 +0,0 @@
-# /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.