@shawnstack/quickforge 1.4.0 → 1.4.1

package/server/custom-commands.mjs

@@ -1,11 +1,59 @@
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import { getEnabledPluginCommandSources } from './plugins/registry.mjs'
+import { userCommandsDir } from './storage.mjs'
 
 const commandsRelativeDirs = ['.claude/commands', '.opencode/commands', '.ai/commands']
 const commandsRelativeDir = '.ai/commands'
 const commandNamePattern = /^(?!.*--)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
 
+/**
+ * Centralized metadata for all built-in slash commands.
+ * This is the single source of truth used by /help output.
+ * Front-end i18n descriptions (i18n.ts) should be kept in sync with the
+ * `description` values here.
+ */
+const builtinCommandCatalog = [
+  {
+    name: 'plan',
+    description: 'Create a plan first; this turn cannot edit files or run commands.',
+    argumentHint: '[task]',
+    permissionNote: 'read-only',
+  },
+  {
+    name: 'review',
+    description: 'Review pending code changes before commit; this turn cannot edit files.',
+    argumentHint: '[scope]',
+    permissionNote: 'no edits',
+  },
+  {
+    name: 'compact',
+    description: 'Create a new chat with this conversation compacted to reduce context usage.',
+    argumentHint: '',
+  },
+  {
+    name: 'clear',
+    description: 'Clear the current chat history and context without calling the model.',
+    argumentHint: '',
+  },
+  {
+    name: 'commands',
+    description: 'List custom commands (project, user-level, and plugin).',
+    argumentHint: '',
+  },
+  {
+    name: 'command new',
+    description: 'Create a project custom command template.',
+    argumentHint: '<name>',
+  },
+  {
+    name: 'help',
+    aliases: ['?'],
+    description: 'Show available commands and their usage.',
+    argumentHint: '',
+  },
+]
+
 function normalizeCommandName(value) {
   const name = String(value || '').trim().toLowerCase()
   return commandNamePattern.test(name) ? name : null
@@ -103,7 +151,7 @@ function firstOptionalBoolean(...values) {
   return undefined
 }
 
-function commandFromFile(file, text, options = {}) {
+export function commandFromFile(file, text, options = {}) {
   const parsed = parseFrontmatter(text)
   if (!parsed.body) return null
 
@@ -229,13 +277,27 @@ async function listPluginCommands(workspaceRoot) {
   return commands
 }
 
+async function listUserCommands() {
+  return listCommandsFromDirectory(userCommandsDir, {
+    source: 'user',
+    relativeRoot: '~/.quickforge/commands',
+  })
+}
+
 export async function listProjectCommands(workspaceRoot, commandDir) {
   const byName = new Map()
 
+  // 1. Plugin commands (lowest priority)
   for (const command of (await listPluginCommands(workspaceRoot)).sort((a, b) => a.name.localeCompare(b.name))) {
     byName.set(command.name, command)
   }
 
+  // 2. User-level commands (~/.quickforge/commands/) — override plugins, overridden by project
+  for (const command of (await listUserCommands()).sort((a, b) => a.name.localeCompare(b.name))) {
+    byName.set(command.name, command)
+  }
+
+  // 3. Project directories: .claude → .opencode → .ai → configured (highest priority)
   for (const dir of commandDirectories(workspaceRoot, commandDir)) {
     const commands = await listCommandsFromDirectory(dir)
     for (const command of commands.sort((a, b) => a.name.localeCompare(b.name))) {
@@ -297,6 +359,7 @@ function escapeXml(value) {
 
 export function parseInternalCommandInvocation(message) {
   const text = textFromUserMessage(message).trim()
+  if (/^\/(?:help|\?)(?:\s+.*)?$/i.test(text)) return { type: 'help' }
   if (/^\/commands(?:\s+.*)?$/i.test(text)) return { type: 'list' }
   if (/^\/clear\s*$/i.test(text)) return { type: 'clear' }
   if (/^\/clear(?:\s+[\s\S]+)$/i.test(text)) return { type: 'invalid-clear-args' }
@@ -344,14 +407,19 @@ export async function handleInternalCommand(invocation, workspaceRoot, commandDi
     return 'Usage: /clear'
   }
 
-  if (!workspaceRoot) {
-    return 'Custom commands require an active project chat.'
+  if (invocation.type === 'help') {
+    return formatHelpText(await listProjectCommands(workspaceRoot, commandDir))
   }
 
+  // /commands and /help work without a project (user-level commands are global)
   if (invocation.type === 'list') {
     return formatCommandList(await listProjectCommands(workspaceRoot, commandDir))
   }
 
+  if (!workspaceRoot) {
+    return 'Custom commands require an active project chat.'
+  }
+
   if (invocation.type === 'new') {
     return createCommandTemplate(workspaceRoot, invocation.name)
   }
@@ -367,17 +435,17 @@ function formatPermission(value) {
   return value === false ? 'false' : 'true'
 }
 
-function formatCommandList(commands) {
+export function formatCommandList(commands) {
   if (commands.length === 0) {
     return [
-      'No project custom commands found.',
+      'No custom commands found.',
       '',
       'Create one with:',
       '```text',
       '/command new review',
       '```',
       '',
-      'Or add Markdown files under `.claude/commands/`, `.opencode/commands/`, or `.ai/commands/`, for example `.ai/commands/review.md`.',
+      'Or add Markdown files under `~/.quickforge/commands/` (user-level), or `.claude/commands/`, `.opencode/commands/`, `.ai/commands/` (project-level), for example `.ai/commands/review.md`.',
     ].join('\n')
   }
 
@@ -389,37 +457,59 @@ function formatCommandList(commands) {
   })
 
   return [
-    'Project custom commands:',
+    'Custom commands:',
     '',
     ...rows,
     '',
-    'Command files live in `.claude/commands/*.md`, `.opencode/commands/*.md`, `.ai/commands/*.md`, or configured directories. Use `$ARGUMENTS` inside a command file to insert invocation arguments.',
+    'Command files live in `~/.quickforge/commands/*.md` (user-level), `.claude/commands/*.md`, `.opencode/commands/*.md`, `.ai/commands/*.md`, or configured directories. Use `$ARGUMENTS` inside a command file to insert invocation arguments.',
   ].join('\n')
 }
 
-async function createCommandTemplate(workspaceRoot, name) {
-  const commandName = normalizeCommandName(name)
-  if (!commandName) {
-    return `Invalid command name: ${name}\n\nUse lowercase letters, numbers, and hyphens.`
-  }
+function formatBuiltinCommandRows() {
+  return builtinCommandCatalog.map((cmd) => {
+    const hint = cmd.argumentHint ? ` ${cmd.argumentHint}` : ''
+    const aliases = cmd.aliases?.length
+      ? ` (alias: ${cmd.aliases.map((alias) => `/${alias}`).join(', ')})`
+      : ''
+    const perm = cmd.permissionNote ? ` \[${cmd.permissionNote}\]` : ''
+    return `- \`/${cmd.name}${hint}\`${aliases} — ${cmd.description}${perm}`
+  })
+}
 
-  const dir = commandDirectory(workspaceRoot)
-  const file = path.join(dir, `${commandName}.md`)
-  try {
-    await fs.mkdir(dir, { recursive: true })
-    await fs.writeFile(file, commandTemplate(commandName), { encoding: 'utf8', flag: 'wx' })
-  } catch (error) {
-    if (error?.code === 'EEXIST') {
-      return `Custom command already exists: ${commandsRelativeDir}/${commandName}.md`
-    }
-    throw error
+export function formatHelpText(customCommands = []) {
+  const sections = [
+    'QuickForge command reference',
+    '',
+    'Built-in commands:',
+    '',
+    ...formatBuiltinCommandRows(),
+  ]
+
+  if (customCommands.length > 0) {
+    sections.push('', formatCommandList(customCommands))
+  } else {
+    sections.push(
+      '',
+      'No custom commands found. Add Markdown files under `~/.quickforge/commands/` (user-level) or `.claude/commands/`, `.opencode/commands/`, `.ai/commands/` (project-level).',
+    )
   }
 
-  return [
-    `Created custom command: ${commandsRelativeDir}/${commandName}.md`,
-    '',
-    `Run it with: /${commandName} your arguments`,
-  ].join('\n')
+  return sections.join('\n')
+}
+
+async function createCommandTemplate(workspaceRoot, name) {
+  const result = await createCommandFile(workspaceRoot, name)
+  if (result.ok) {
+    return [
+      `Created custom command: ${result.relativePath}`,
+      '',
+      `Run it with: /${result.name} your arguments`,
+    ].join('\n')
+  }
+  if (result.reason === 'exists') {
+    return `Custom command already exists: ${commandsRelativeDir}/${result.name}.md`
+  }
+  return `Invalid command name: ${name}\n\nUse lowercase letters, numbers, and hyphens.`
 }
 
 function commandTemplate(name) {
@@ -436,3 +526,30 @@ allow_commands: false
 $ARGUMENTS
 `
 }
+
+export async function createCommandFile(workspaceRoot, name) {
+  const commandName = normalizeCommandName(name)
+  if (!commandName) {
+    return { ok: false, reason: 'invalid' }
+  }
+  const dir = commandDirectory(workspaceRoot)
+  if (!dir) {
+    return { ok: false, reason: 'no-project' }
+  }
+  const file = path.join(dir, `${commandName}.md`)
+  try {
+    await fs.mkdir(dir, { recursive: true })
+    await fs.writeFile(file, commandTemplate(commandName), { encoding: 'utf8', flag: 'wx' })
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      return { ok: false, reason: 'exists', name: commandName, filePath: file }
+    }
+    throw error
+  }
+  return {
+    ok: true,
+    name: commandName,
+    filePath: file,
+    relativePath: `${commandsRelativeDir}/${commandName}.md`,
+  }
+}

package/server/mcp/registry.mjs

@@ -231,6 +231,46 @@ export async function refreshMcpConnections() {
   return refreshPromise
 }
 
+export async function reconnectMcpServer(name) {
+  const normalizedName = String(name || '').trim()
+  // close any existing connection first (bypasses retry backoff)
+  const existing = connections.get(normalizedName)
+  if (existing) {
+    connections.delete(normalizedName)
+    await closeConnection(existing)
+  }
+  const servers = await readMcpServers()
+  const config = servers.find((server) => server.name === normalizedName)
+  if (!config) {
+    const error = new Error(`MCP server not found: ${normalizedName}`)
+    error.statusCode = 404
+    throw error
+  }
+  if (!config.enabled) {
+    const error = new Error(`MCP server is disabled: ${normalizedName}`)
+    error.statusCode = 400
+    throw error
+  }
+  try {
+    const connection = await connectServer(config)
+    connections.set(config.name, connection)
+  } catch (error) {
+    logger.error(`Failed to reconnect MCP server ${config.name}:`, error)
+    connections.set(config.name, {
+      config,
+      client: null,
+      transport: null,
+      status: 'error',
+      error: error?.message || 'Failed to connect MCP server',
+      tools: [],
+      connectedAt: null,
+      stderr: '',
+      lastAttemptAt: Date.now(),
+    })
+  }
+  return connections
+}
+
 export async function getMcpStatus() {
   await refreshMcpConnections()
   const servers = await readMcpServers()

package/server/routes/agent.mjs

@@ -83,7 +83,7 @@ export async function handleAgentApi(req, res, url) {
       error.statusCode = 400
       throw error
     }
-    const result = await runPrompt(sessionId, message, body?.selectedCapabilities)
+    const result = await runPrompt(sessionId, message, body?.selectedCapabilities, body?.command)
     sendJson(res, 200, result)
     return
   }

package/server/routes/mcp.mjs

@@ -1,7 +1,7 @@
 import { sendJson, readJsonBody } from '../utils/response.mjs'
 import { refreshAllSessionTools } from '../agent-manager.mjs'
 import { deleteMcpServer, normalizeMcpServers, readMcpServers, setMcpServerEnabled, upsertMcpServer, writeMcpServers } from '../mcp/config.mjs'
-import { getMcpStatus, refreshMcpConnections } from '../mcp/registry.mjs'
+import { getMcpStatus, reconnectMcpServer, refreshMcpConnections } from '../mcp/registry.mjs'
 
 async function refreshMcpAndAgentTools() {
   await refreshMcpConnections()
@@ -54,6 +54,12 @@ export async function handleMcpApi(req, res, url) {
     return
   }
 
+  if (req.method === 'POST' && parts[0] === 'api' && parts[1] === 'mcp' && parts[2] === 'reconnect' && parts[3]) {
+    await reconnectMcpServer(decodeURIComponent(parts[3]))
+    sendJson(res, 200, await refreshMcpAndAgentTools())
+    return
+  }
+
   if (req.method === 'DELETE' && parts[0] === 'api' && parts[1] === 'mcp' && parts[2] === 'servers' && parts[3]) {
     await deleteMcpServer(decodeURIComponent(parts[3]))
     sendJson(res, 200, await refreshMcpAndAgentTools())

package/server/routes/project.mjs

@@ -1,6 +1,6 @@
 import { sendJson, readJsonBody, decodeSegment } from '../utils/response.mjs'
 import { getActiveProject, setActiveProjectPath, readProjectConfig } from '../project-config.mjs'
-import { listProjectCommands } from '../custom-commands.mjs'
+import { listProjectCommands, createCommandFile } from '../custom-commands.mjs'
 import { atomicProjectConfigUpdate } from '../storage.mjs'
 import { getWorkspaceRoot, setWorkspaceRoot } from '../utils/workspace.mjs'
 import { selectDirectoryDialog, openPathInFileManager } from '../utils/platform.mjs'
@@ -20,7 +20,7 @@ export async function handleProjectApi(req, res, url) {
     const project = projectId
       ? config.projects.find((item) => item.id === projectId)
       : getActiveProject(config)
-    const commands = project?.path ? await listProjectCommands(project.path, project.commandDir) : []
+    const commands = await listProjectCommands(project?.path, project?.commandDir)
     sendJson(res, 200, {
       commands: commands.map((command) => ({
         name: command.name,
@@ -29,6 +29,7 @@ export async function handleProjectApi(req, res, url) {
         allowEdit: command.allowEdit,
         allowCommands: command.allowCommands,
         relativePath: command.relativePath,
+        filePath: command.filePath,
         source: command.source,
         pluginName: command.pluginName,
       })),
@@ -107,6 +108,35 @@ export async function handleProjectApi(req, res, url) {
     return
   }
 
+  if (req.method === 'POST' && url.pathname === '/api/project/open-path') {
+    const body = await readJsonBody(req)
+    const active = body?.projectId
+      ? config.projects.find((project) => project.id === body.projectId) ?? getActiveProject(config)
+      : getActiveProject(config)
+    const target = String(body?.path || '')
+    const resolved = target && path.isAbsolute(target)
+      ? path.resolve(target)
+      : path.resolve(active?.path || '', target)
+    await openPathInFileManager(resolved)
+    sendJson(res, 200, { ok: true })
+    return
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/project/command') {
+    const body = await readJsonBody(req)
+    const active = body?.projectId
+      ? config.projects.find((project) => project.id === body.projectId) ?? getActiveProject(config)
+      : getActiveProject(config)
+    if (!active?.path) {
+      const error = new Error('No active project')
+      error.statusCode = 400
+      throw error
+    }
+    const result = await createCommandFile(active.path, body?.name)
+    sendJson(res, 200, result)
+    return
+  }
+
   if (req.method === 'DELETE' && url.pathname.startsWith('/api/project/')) {
     const id = decodeSegment(url.pathname.split('/').filter(Boolean)[2])
     const updated = await atomicProjectConfigUpdate((cfg) => {

package/server/routes/shared-conversation.mjs

@@ -363,7 +363,7 @@ export async function handleSharedConversationApi(req, res, url) {
     assertOperate(record)
     const body = await readJsonBody(req)
     await restoreAgent(record.sessionId)
-    const result = await runPrompt(record.sessionId, messageFromBody(body, record, req))
+    const result = await runPrompt(record.sessionId, messageFromBody(body, record, req), [], body?.command)
     sendJson(res, 200, result)
     return
   }

package/server/storage.mjs

@@ -94,6 +94,7 @@ export const configDir = path.join(dataDir, 'config')
 export const storageDir = path.join(dataDir, 'storage')
 export const cacheDir = path.join(dataDir, 'cache')
 export const logsDir = path.join(dataDir, 'logs')
+export const userCommandsDir = path.join(dataDir, 'commands')
 
 const quickForgeConfigFile = path.join(configDir, 'config.json')
 const configMigrationMarkerFile = path.join(configDir, '.layout-migrated')

package/server/subagents.mjs

@@ -21,23 +21,23 @@ export const subagentDefinitions = [
     name: 'general',
     label: 'General',
     mode: 'subagent',
-    description: 'A general-purpose agent for researching complex problems and executing multi-step tasks. It has full built-in workspace tool access, excluding MCP tools and Agent Skills, so it can modify files when needed. Use it for substantial independent work units, including parallelizable work.',
+    description: 'A general-purpose agent for bounded complex multi-step implementation or broader independent work. It has full built-in workspace tool access, excluding MCP tools and Agent Skills, so it can modify files when needed. Prefer Explore for focused read-only repository discovery, source search, call-chain lookup, tests/docs discovery, and impact analysis.',
     allowedTools: ['read_file', 'grep_files', 'write_file', 'edit_file', 'run_command'],
     allowFileMutations: true,
     maxRuntimeMs: 30 * 60 * 1000,
     maxToolCalls: 300,
-    systemPrompt: `You are General, a general-purpose subagent for complex research and multi-step implementation tasks. You may inspect, edit, write files, and run commands using the built-in workspace tools when needed. You do not have MCP tools or Agent Skills. Make focused, minimal changes that satisfy the delegated task, and verify your changes when appropriate.`,
+    systemPrompt: `You are General, a general-purpose subagent for bounded complex multi-step implementation tasks and broader independent work. You may inspect, edit, write files, and run commands using the built-in workspace tools when needed. You do not have MCP tools or Agent Skills. Prefer Explore for focused read-only repository discovery, source search, call-chain lookup, tests/docs discovery, and impact analysis. Make focused, minimal changes that satisfy the delegated task, and verify your changes when appropriate.`,
   },
   {
     name: 'explore',
     label: 'Explore',
     mode: 'subagent',
-    description: 'A fast read-only agent for targeted exploration and focused questions. It cannot modify files. Use it to quickly find relevant files, search keywords, identify patterns, or summarize findings.',
-    allowedTools: ['read_file', 'grep_files'],
+    description: 'The preferred subagent for focused read-only repository exploration, file discovery, source search, call-chain lookup, related tests/docs/wiki discovery, safe inspection commands, pattern lookup, and impact analysis before non-trivial implementation. It cannot modify files.',
+    allowedTools: ['read_file', 'grep_files', 'run_command'],
     allowFileMutations: false,
     maxRuntimeMs: 30 * 60 * 1000,
     maxToolCalls: 300,
-    systemPrompt: `You are Explore, a fast read-only exploration subagent. Use read_file and grep_files to locate relevant files, search keywords, identify patterns, and answer focused questions. You cannot modify files or run commands.`,
+    systemPrompt: `You are Explore, the preferred read-only repository exploration subagent. Use read_file, grep_files, and safe read-only run_command calls to locate files, inspect project structure, search source, trace call chains, find related tests/docs/wiki pages, run diagnostics, identify patterns, assess impact, and answer focused questions before non-trivial implementation. You cannot modify files.`,
   },
 ]
 
@@ -80,7 +80,9 @@ export function composeSubagentSystemPrompt({ definition, parentSystemPrompt, pr
     '- run_subagent is not available to subagents.',
     definition.allowFileMutations
       ? '- File modification tools are available when needed, subject to the parent session approval/YOLO policy.'
-      : '- This subagent is read-only. Do not modify files or run commands.',
+      : definition.allowedTools.includes('run_command')
+        ? '- This subagent is read-only. Do not modify files. Use run_command only for safe inspection or diagnostic commands.'
+        : '- This subagent is read-only. Do not modify files or run commands.',
     workspaceLines.length ? `\nWorkspace context:\n${workspaceLines.join('\n')}` : '',
     '</subagent_instructions>',
   ].filter(Boolean).join('\n')

package/server/system-prompt.mjs

@@ -8,7 +8,7 @@ For project tasks:
 - For multi-step work, use a brief plan.
 - Before changing files, gather sufficient context: relevant files, entry points or call chains, existing patterns, tests or validation commands, and docs/wiki impact.
 - Before taking action, confirm with the user.
-- Unless the change is trivial and localized to an already-known file, use Explore first for read-only repository research; prefer Explore for broad searches, pattern lookup, impact analysis, and locating related tests, docs, or build scripts.
+- Unless the change is trivial and localized to an already-known file, use Explore first for read-only repository research before implementation decisions; prefer Explore for file discovery, source location, broad searches, call-chain lookup, pattern lookup, impact analysis, and locating related tests, docs, wiki pages, or build scripts.
 - For complex multi-step work, use General only for bounded assistance; the parent assistant remains responsible for final decisions, minimal edits, and verification.
 - Make minimal, focused changes.
 - Prefer dedicated workspace tools for reading, editing, and searching files.
@@ -63,7 +63,7 @@ function appendSubagentCatalog(parts, subagents) {
   const subagentParts = subagents.map(formatSubagentCatalogItem)
   parts.push(`
 <available_subagents>
-The run_subagent tool can delegate work to an enabled temporary Agent Profile. Built-in profiles include Explore for fast read-only codebase search and General for complex multi-step implementation work; custom profiles may also be available when enabled.
+The run_subagent tool can delegate work to an enabled temporary Agent Profile. Prefer Explore for focused read-only repository discovery before implementation decisions, including locating files, searching source, tracing call chains, finding related tests/docs/wiki pages, and impact analysis. Use General for bounded complex multi-step implementation or broader independent work; custom profiles may also be available when enabled.
 
 Choose the most appropriate subagent by name, keep delegation concrete, and include relevant context. Treat subagent output as advisory; you remain responsible for the final answer.
 

package/server/tools/definitions.mjs

@@ -15,7 +15,7 @@ import { loadSelectedGlobalSkills, loadSelectedProjectSkills, mergeSkills } from
 export const subagentTool = {
   name: 'run_subagent',
   label: 'Run subagent',
-  description: 'Delegate a bounded task to an enabled temporary Agent Profile. Built-in profiles include general for complex multi-step work and explore for fast read-only lookup. Custom profiles can also be enabled as subagents. Subagents are short-lived and do not receive MCP or Agent Skill tools.',
+  description: 'Delegate a bounded task to an enabled temporary Agent Profile. Prefer explore for focused read-only repository discovery before implementation decisions, including locating files, searching source, tracing call chains, finding related tests/docs/wiki pages, and impact analysis. Use general for bounded complex multi-step implementation or broader independent work. Custom profiles can also be enabled as subagents. Subagents are short-lived and do not receive MCP or Agent Skill tools.',
   parameters: Type.Object({
     subagent: Type.String({ description: 'Agent Profile name to invoke.' }),
     task: Type.String({ description: 'Concrete, bounded task for the subagent. Do not delegate vague or open-ended work.' }),