internaltool-mcp 1.6.42 → 1.6.45

package/index.js

@@ -520,73 +520,69 @@ After approval, the skill/rule is injected at every future kickoff_task.`,
   // ── plan_task_from_codebase ───────────────────────────────────────────────────
   server.tool(
     'plan_task_from_codebase',
-    `Specialized task-creation agent — analyzes the codebase and creates a fully structured, kickoff-ready task.
-
-Use this instead of create_task when you need to implement something and want the task to
-contain a real implementation plan based on the actual codebase, not a generic description.
+    `Specialized task-creation agent — scouts the codebase, sets up the agent config, and creates a fully-planned, kickoff-ready task.
 
 ## MANDATORY protocol — follow every step in order
 
-### Step 1 — Duplicate check (always first)
+### Step 1 — Duplicate check
 Call search_tasks(projectId, query="<keywords from the request>").
-If a similar open task already exists → return it with kickoff instructions instead of creating a duplicate.
+If a similar open task exists → return it with kickoff instructions. Do NOT create a duplicate.
 
-### Step 2 — Codebase analysis (READ the code, do not guess)
+### Step 2 — Codebase scout (READ the code — do not guess)
 Using your native Read / Grep / Glob tools:
 
 a) **Stack detection** — read package.json / go.mod / requirements.txt / Cargo.toml.
-   Identify: language, framework, major libraries, test runner.
-
-b) **Entry point mapping** — find where the relevant feature area lives:
-   - For backend: grep for existing route patterns (router.post, app.get, @Controller, etc.)
-   - For frontend: grep for existing component patterns, hooks, state management
-   - For DB: find schema/model files
-
-c) **Pattern extraction** — read 2-3 existing files similar to what you'll build.
-   Note: naming conventions, folder structure, how services/routes/components are wired.
-
-d) **Impact analysis** — identify every file that needs to change:
-   - Files to CREATE (new route, new component, new model, new test)
-   - Files to MODIFY (existing router index, existing schema, existing types)
-
-e) **Dependency order** — which files must be built first (schema before service, service before route, etc.)
-
-### Step 3 — Write the implementation plan
-Using what you found in Step 2, build:
+b) **Entry point mapping** — grep for route/component/schema patterns relevant to the feature.
+c) **Pattern extraction** — read 2–3 files similar to what you'll build. Note naming conventions, folder structure, wiring patterns.
+d) **Impact analysis** — list every file to CREATE and every file to MODIFY.
+e) **Dependency order** — schema → model → service → route → test → UI.
+
+### Step 3 — Agent config analysis (use agentConfigAnalysis returned by this tool)
+The tool returns agentConfigAnalysis showing what the project already has and what it needs.
+Act on it BEFORE creating the task:
+
+**a) suggest_skill for each item in agentConfigAnalysis.suggestForProject:**
+   Call suggest_skill(projectId, type, name, description, body, rationale, sourceTaskKey)
+   — one call per missing skill/rule. Use the body template from agentConfigAnalysis.suggestBodyTemplate.
+   These go to the admin approval queue and will be injected at every future kickoff.
+
+**b) Set task-level kit via agentKitOverrides in create_task:**
+   Pass agentKitOverrides = agentConfigAnalysis.taskKitOverrides
+   — this pre-selects the right agents/skills/prompts for THIS task without touching project-level config.
+
+**c) Use remember() for facts that cannot be expressed as a skill or rule:**
+   After create_task, call remember(taskId, key, value) for each fact in agentConfigAnalysis.rememberFacts.
+   Examples: "auth_module = server/middleware/auth.js", "test_runner = jest --runInBand"
+
+### Step 4 — Write the implementation plan
+Using findings from Step 2:
 - ## Goal — one sentence
-- ## Stack — language/framework detected
-- ## Technical approach — how it fits into the existing code (name actual files and functions)
-- ## Files to create — path + what it does
-- ## Files to modify — path + what changes
-- ## Subtasks — ordered implementation steps (schema → service → route → test → UI)
-- ## Acceptance criteria — what done looks like
-
-### Step 4 — Determine task metadata
-- taskType: feature / bugfix / migration / integration / ui / backend / security / refactor
-- priority: low / medium / high / critical (use "high" if the request sounds important)
-- suggestedFiles: the exact file paths from your Step 2d impact analysis
+- ## Stack — detected stack
+- ## Technical approach — real file names and functions
+- ## Files to create
+- ## Files to modify
+- ## Subtasks — ordered steps
+- ## Acceptance criteria
 
 ### Step 5 — Create the task
 Call create_task with:
-- projectId (from this call)
-- title: action-oriented, concise (verb + noun, e.g. "Add rate limiting to /api/auth/login")
-- description: one paragraph summary
-- readmeMarkdown: the full plan from Step 3
-- taskType, priority, column="todo"
-- subtasks: the ordered list from Step 3 (each step = one subtask)
-- suggestedFiles: from Step 2d
-
-After create_task succeeds, immediately call:
-kickoff_task(taskId=<returned id>, confirmed=true, agentRole="builder", files=<suggestedFiles>)
-
-## What makes a high-quality task
-- readmeMarkdown references REAL file paths found by grepping the codebase
-- subtasks are ordered (schema first, then service, then route, then test, then UI)
-- suggestedFiles lists every file that will be touched — no omissions
-- title is specific ("Add email verification to /api/auth/register") not generic ("Add email feature")
-
-Do NOT skip the codebase analysis. Do NOT create the task before reading the code.
-Do NOT ask the developer to describe the codebase — read it yourself.`,
+- projectId, title (verb+noun), description, readmeMarkdown, taskType, priority, column="todo"
+- subtasks (ordered), suggestedFiles (from Step 2d)
+- agentKitOverrides from Step 3b
+
+### Step 6 — Post-creation setup
+1. For each fact in agentConfigAnalysis.rememberFacts: call remember(taskId, key, value)
+2. Log to session: call log_session_event(taskId, type="info", name="task-created", summary="Scouted codebase, configured kit, created task")
+3. Present the approval summary to the developer and wait for submit_task_for_approval confirmation
+
+## Quality checklist
+- readmeMarkdown references REAL file paths
+- subtasks are ordered (schema → model → service → route → test → UI)
+- agentKitOverrides is set based on task type
+- suggest_skill was called for any missing project-level skills
+- remember() was called for codebase-specific facts
+
+Do NOT skip the scout phase. Do NOT ask the developer to describe the codebase.`,
     {
       projectId: z.string().describe("InternalTool project's MongoDB ObjectId — from the project's task board URL or CLAUDE.md"),
       request:   z.string().describe('What the developer wants to build — the raw natural language request (e.g. "add rate limiting to the login endpoint", "fix the pagination bug on users list")'),
@@ -604,8 +600,9 @@ Do NOT ask the developer to describe the codebase — read it yourself.`,
       const dirTree     = getDirTree(cwd, 2)
       const entryPoints = findEntryPoints(cwd, stack)
 
-      // ── 2. Fetch project context ──────────────────────────────────────────────
+      // ── 2. Fetch project context + existing agentConfig ─────────────────────
       let projectContext = null
+      let existingAgentConfig = { skills: [], rules: [], subagents: [], prompts: [] }
       try {
         const projRes = await api.get(`/api/projects/${projectId}`)
         if (projRes?.success) {
@@ -615,6 +612,13 @@ Do NOT ask the developer to describe the codebase — read it yourself.`,
             taskCount:  (projRes.data.tasks || []).length,
             githubRepo: p.github?.repoUrl || null,
           }
+          const cfg = p.agentConfig || {}
+          existingAgentConfig = {
+            skills:    (cfg.skills    || []).map(s => s.name),
+            rules:     (cfg.rules     || []).map(r => r.name),
+            subagents: (cfg.subagents || []).map(a => a.name),
+            prompts:   (cfg.prompts   || []).map(p => p.name),
+          }
         }
       } catch { /* non-fatal */ }
 
@@ -632,7 +636,102 @@ Do NOT ask the developer to describe the codebase — read it yourself.`,
         }
       } catch { /* non-fatal */ }
 
-      // ── 4. Return codebase intelligence + tight instructions ──────────────────
+      // ── 4. Agent config gap analysis ─────────────────────────────────────────
+      // Determine what kit the task needs based on stack + request keywords
+      const requestCorpus = `${request} ${stack.language || ''} ${stack.framework || ''} ${(stack.extra || []).join(' ')}`.toLowerCase()
+
+      // Map task type keywords → what kit category is relevant
+      const KIT_CATEGORY_HINTS = {
+        security:    ['auth', 'security', 'jwt', 'password', 'permission', 'rbac', 'owasp', 'token', 'encrypt', 'rate limit', 'sanitize'],
+        scout:       ['explore', 'understand', 'architecture', 'trace', 'how does', 'what is', 'map', 'audit', 'recon', 'investigate'],
+        merge:       ['merge', 'rebase', 'conflict', 'ship', 'push', 'pr', 'branch'],
+        review:      ['review', 'code review', 'diff', 'approve', 'feedback', 'pull request'],
+        coordinator: ['large', 'complex', 'parallel', 'coordinate', 'orchestrate', 'decompose', 'multi-step'],
+        builder:     ['build', 'implement', 'create', 'add', 'fix', 'feature', 'endpoint', 'route', 'component', 'model', 'service', 'crud'],
+      }
+      let detectedKitCategory = 'builder'
+      let maxKitScore = 0
+      for (const [cat, keywords] of Object.entries(KIT_CATEGORY_HINTS)) {
+        const score = keywords.filter(kw => requestCorpus.includes(kw)).length
+        if (score > maxKitScore) { maxKitScore = score; detectedKitCategory = cat }
+      }
+
+      // Kit catalog — what skills/agents/prompts exist in ZopKit
+      const ZOPKIT_SKILLS_CATALOG  = ['zop-blueprint', 'zop-recon', 'zop-guard-skill', 'zop-merge-skill', 'zop-review-skill', 'session-start']
+      const ZOPKIT_AGENTS_CATALOG  = ['zop-shipper', 'zop-scout', 'zop-guard', 'zop-merger', 'zop-reviewer', 'zop-orchestrator']
+      const ZOPKIT_PROMPTS_CATALOG = ['ship-feature', 'codebase-recon', 'security-sweep', 'merge-guide', 'review-pr']
+
+      // Recommended kit for detected category
+      const KIT_RECOMMENDATIONS = {
+        builder:     { skills: ['zop-blueprint', 'session-start'], agents: ['zop-shipper'],      prompts: ['ship-feature'] },
+        scout:       { skills: ['zop-recon', 'session-start'],     agents: ['zop-scout'],        prompts: ['codebase-recon'] },
+        security:    { skills: ['zop-guard-skill', 'session-start'], agents: ['zop-guard'],      prompts: ['security-sweep'] },
+        merge:       { skills: ['zop-merge-skill', 'session-start'], agents: ['zop-merger'],     prompts: ['merge-guide'] },
+        review:      { skills: ['zop-review-skill', 'session-start'], agents: ['zop-reviewer'],  prompts: ['review-pr'] },
+        coordinator: { skills: ['zop-blueprint', 'zop-recon', 'session-start'], agents: ['zop-orchestrator'], prompts: ['ship-feature'] },
+      }
+      const recommendedKit = KIT_RECOMMENDATIONS[detectedKitCategory] || KIT_RECOMMENDATIONS.builder
+
+      // What's already in the project vs what's missing
+      const missingSkills  = recommendedKit.skills.filter(s => !existingAgentConfig.skills.includes(s))
+      const missingAgents  = recommendedKit.agents.filter(a => !existingAgentConfig.subagents.includes(a))
+      const missingPrompts = recommendedKit.prompts.filter(p => !existingAgentConfig.prompts.includes(p))
+
+      // Task-level overrides: enable recommended, disable irrelevant
+      const taskKitOverrides = {
+        skills:    Object.fromEntries([
+          ...existingAgentConfig.skills.map(s => [s, recommendedKit.skills.includes(s)]),
+          ...recommendedKit.skills.filter(s => !existingAgentConfig.skills.includes(s)).map(s => [s, false]), // not in project yet — pending suggest_skill
+        ]),
+        subagents: Object.fromEntries(existingAgentConfig.subagents.map(a => [a, recommendedKit.agents.includes(a)])),
+        prompts:   Object.fromEntries(existingAgentConfig.prompts.map(p => [p, recommendedKit.prompts.includes(p)])),
+      }
+
+      // Stack-derived codebase facts that should be persisted via remember()
+      const rememberFacts = [
+        stack.language    && { key: 'stack_language',    value: stack.language },
+        stack.framework   && { key: 'stack_framework',   value: stack.framework },
+        stack.testRunner  && { key: 'stack_test_runner', value: stack.testRunner },
+        stack.packageManager && { key: 'stack_pkg_manager', value: stack.packageManager },
+        entryPoints.routes?.[0]     && { key: 'entry_routes',  value: entryPoints.routes[0] },
+        entryPoints.models?.[0]     && { key: 'entry_models',  value: entryPoints.models[0] },
+        entryPoints.components?.[0] && { key: 'entry_components', value: entryPoints.components[0] },
+      ].filter(Boolean)
+
+      // Skill suggestion templates for each missing item
+      const SKILL_BODY_TEMPLATES = {
+        'zop-blueprint':    `## Feature Blueprint\n1. Define the data model / schema changes\n2. Build the API layer (route → service → model)\n3. Build the frontend (component → hook → API call)\n4. Wire everything together\n5. Write tests (unit + integration)\n6. Update README / docs`,
+        'zop-recon':        `## Codebase Recon\n1. Read entry points: routes, models, middleware, utils\n2. Map the data flow end-to-end\n3. Identify patterns: naming conventions, error handling, auth\n4. Find gaps: missing tests, dead code, undocumented APIs\n5. Write findings to scout_task`,
+        'zop-guard-skill':  `## Security Audit\n1. Check authentication (JWT expiry, refresh, revocation)\n2. Check authorization (role checks on every sensitive route)\n3. Check input validation (Zod/Joi on all user inputs)\n4. Check for injection (SQL, NoSQL, command)\n5. Check error messages (no stack traces exposed)\n6. Run OWASP Top 10 checklist`,
+        'zop-merge-skill':  `## Merge & Ship\n1. git fetch origin && git rebase origin/main\n2. Resolve any conflicts using resolve_conflict tool\n3. Run full test suite — must be green\n4. Push with --force-with-lease\n5. Verify PR CI passes\n6. Request final review`,
+        'zop-review-skill': `## Code Review\n1. Read the task README to understand intent\n2. Review each changed file: correctness, edge cases, security\n3. Check test coverage: are new paths tested?\n4. Check for breaking changes\n5. Post review with specific file+line comments\n6. Approve or request changes`,
+        'session-start':    `## Session Start\n1. Call recall(taskId) to restore memory from previous sessions\n2. Call get_agent_context(taskId) for the full implementation plan\n3. Check local git state: \`git status\`\n4. Check branch: \`git branch --show-current\`\n5. Read any changed files since last session\n6. Resume work from where you left off`,
+      }
+      const AGENT_BODY_TEMPLATES = {
+        'zop-shipper':      `You are a builder agent. Your job is to implement code end-to-end.\nConstraints:\n- Only modify files listed in claimedFiles\n- Every change needs a test\n- Run tests before marking done\n- Never modify auth middleware without explicit approval`,
+        'zop-scout':        `You are a scout agent. Your job is to map the codebase — READ ONLY.\nConstraints:\n- Never write or modify any file\n- Read every source file systematically\n- Write findings via scout_task tool\n- Focus on: data flow, auth, API surface, test coverage, gaps`,
+        'zop-guard':        `You are a security audit agent.\nConstraints:\n- Check auth, authorization, input validation, and OWASP Top 10\n- Report findings as structured issues, not inline comments\n- Never modify security-critical code without explicit admin approval`,
+        'zop-orchestrator': `You are a coordinator agent. Your job is to decompose and delegate — NO CODE.\nConstraints:\n- Call decompose_task to break work into parallel subtasks\n- Call get_parallel_kickoffs to generate builder prompts\n- Never implement anything yourself\n- Each subtask must have exclusive file ownership`,
+      }
+
+      const suggestForProject = [
+        ...missingSkills.map(name => ({
+          type: 'skill',
+          name,
+          description: `${name} — ${ZOPKIT_SKILLS_CATALOG.includes(name) ? 'ZopKit standard skill' : 'custom skill'}`,
+          body: SKILL_BODY_TEMPLATES[name] || `## ${name}\n[Add instructions here]`,
+          rationale: `Detected task type: ${detectedKitCategory}. This skill guides the builder through the ${name.replace('zop-', '').replace('-skill', '')} process in this codebase.`,
+        })),
+        ...missingAgents.map(name => ({
+          type: 'subagent',
+          name,
+          description: `${name} — ${ZOPKIT_AGENTS_CATALOG.includes(name) ? 'ZopKit standard agent' : 'custom agent'}`,
+          body: AGENT_BODY_TEMPLATES[name] || `## ${name} Agent\n[Add role instructions here]`,
+          rationale: `Detected task type: ${detectedKitCategory}. This agent persona enforces the right constraints for ${name.replace('zop-', '')} sessions.`,
+        })),
+      ]
+
+      // ── 5. Return codebase intelligence + tight instructions ──────────────────
       const hasEntryPoints = Object.keys(entryPoints).length > 0
       const stackSummary = [
         stack.language, stack.framework, stack.testRunner, ...(stack.extra || [])
@@ -649,6 +748,26 @@ Do NOT ask the developer to describe the codebase — read it yourself.`,
             : { note: 'No entry points found at cwd — check that MCP server is running from the project root' },
         },
 
+        // Agent config analysis — act on this BEFORE calling create_task
+        agentConfigAnalysis: {
+          detectedKitCategory,
+          recommendedKit,
+          existingProjectConfig: existingAgentConfig,
+          missingFromProject: { skills: missingSkills, agents: missingAgents, prompts: missingPrompts },
+          suggestForProject,   // call suggest_skill for each item here
+          taskKitOverrides,    // pass as agentKitOverrides to create_task
+          rememberFacts,       // call remember(taskId, key, value) for each after create_task
+          instruction: [
+            suggestForProject.length > 0
+              ? `⚠️  ${suggestForProject.length} item(s) are missing from project config — call suggest_skill for each before creating the task.`
+              : `✅ Project config already has the recommended kit for ${detectedKitCategory} tasks.`,
+            `Pass taskKitOverrides as agentKitOverrides in create_task to pre-configure this task.`,
+            rememberFacts.length > 0
+              ? `After create_task, call remember(taskId, key, value) for ${rememberFacts.length} codebase fact(s) so future sessions don't need to re-scout.`
+              : null,
+          ].filter(Boolean).join('\n'),
+        },
+
         // Duplicate guard
         ...(similarTasks?.length > 0 && {
           duplicateWarning: true,
@@ -656,16 +775,21 @@ Do NOT ask the developer to describe the codebase — read it yourself.`,
           duplicateInstruction: 'Check the list above. If one matches → call kickoff_task on it. If none match → proceed.',
         }),
 
-        // What to do now — use codebaseIntelligence above to skip re-reading the filesystem
+        // What to do now
         nextSteps: [
-          'Use dirTree + entryPoints above to identify which files need changing — you already have the map.',
-          `Read 2-3 files from entryPoints.routes / entryPoints.models / entryPoints.components to extract naming conventions and wiring patterns.`,
-          'Draft readmeMarkdown with: ## Goal, ## Stack, ## Technical approach (name real files), ## Files to create, ## Files to modify, ## Subtasks (ordered), ## Acceptance criteria.',
-          `Call create_task(projectId="${projectId}", title="<verb + noun>", readmeMarkdown="<plan>", taskType="<feature|bugfix|...>", priority="${priority}", column="todo", subtasks=[...], suggestedFiles=[...])`,
-          'Immediately after: call kickoff_task(taskId=<returned id>, confirmed=true, agentRole="builder", files=[...suggestedFiles])',
-        ],
+          suggestForProject.length > 0
+            ? `FIRST: call suggest_skill for each item in agentConfigAnalysis.suggestForProject (${suggestForProject.length} item(s)). Use the body and rationale from the array.`
+            : null,
+          'Read 2-3 files from entryPoints.routes / entryPoints.models / entryPoints.components to extract naming conventions.',
+          'Draft readmeMarkdown: ## Goal, ## Stack, ## Technical approach, ## Files to create, ## Files to modify, ## Subtasks, ## Acceptance criteria.',
+          `Call create_task(projectId="${projectId}", title="<verb+noun>", readmeMarkdown="<plan>", taskType="<type>", priority="${priority}", column="todo", subtasks=[...], suggestedFiles=[...], agentKitOverrides=agentConfigAnalysis.taskKitOverrides)`,
+          'After create_task: call remember(taskId, key, value) for each fact in agentConfigAnalysis.rememberFacts.',
+          'Then: call log_session_event(taskId, type="info", name="task-created", summary="Codebase scouted, kit configured, task created").',
+          'Then: call kickoff_task(taskId, confirmed=false) to preview the plan and check git state.',
+          'Then: call submit_task_for_approval(taskId, summary="<3-8 sentence summary>", reviewerId="<admin id>").',
+          'After approval: call kickoff_task(taskId, confirmed=true, agentRole="builder", files=[...suggestedFiles]).',
+        ].filter(Boolean),
 
-        // Context
         request,
         projectId,
         priority,
@@ -715,8 +839,13 @@ Always prefer column="todo" so the task is visibly ready to start.`,
         .describe('Ordered implementation checklist — shown in the task UI and read by agents at kickoff. Order matters: schema → model → service → route → test → frontend.'),
       suggestedFiles: z.array(z.string()).optional()
         .describe('Files the builder will claim at kickoff (e.g. ["server/routes/tasks.js", "server/models/Task.js"]). Included in the task README automatically so the builder knows what to pass to kickoff_task files=[...].'),
+      agentKitOverrides: z.object({
+        skills:    z.record(z.boolean()).optional(),
+        subagents: z.record(z.boolean()).optional(),
+        prompts:   z.record(z.boolean()).optional(),
+      }).optional().describe('Task-level skill/agent/prompt overrides — pass agentConfigAnalysis.taskKitOverrides from plan_task_from_codebase to pre-configure the right kit for this task.'),
     },
-    async ({ projectId, suggestedFiles, ...taskData }) => {
+    async ({ projectId, suggestedFiles, agentKitOverrides, ...taskData }) => {
       try { assertProjectScope(projectId) } catch (e) { return errorText(e.message) }
 
       // Append suggested files section to the README so the builder sees them at kickoff
@@ -736,18 +865,37 @@ Always prefer column="todo" so the task is visibly ready to start.`,
       if (!res?.success) return errorText(res?.message || 'Failed to create task')
 
       const task = res.data?.task
+
+      // Apply agentKitOverrides immediately if provided
+      let kitApplied = null
+      if (task?._id && agentKitOverrides && Object.keys(agentKitOverrides).length > 0) {
+        try {
+          const kitRes = await api.patch(`/api/tasks/${task._id}`, { agentKitOverrides })
+          kitApplied = kitRes?.success
+            ? { applied: true, overrides: agentKitOverrides }
+            : { applied: false, reason: kitRes?.message }
+        } catch { kitApplied = { applied: false, reason: 'patch failed' } }
+      }
+
       return text({
-        created:   true,
-        taskId:    task?._id,
-        taskKey:   task?.key,
-        title:     task?.title,
-        column:    task?.column,
-        taskType:  task?.taskType || null,
-        subtasks:  (task?.subtasks || []).length,
-        kickoff:   task?._id
-          ? `kickoff_task(taskId="${task._id}", confirmed=false)  ← read plan first\nkickoff_task(taskId="${task._id}", confirmed=true, agentRole="builder", files=[...])  ← start building`
+        created:    true,
+        taskId:     task?._id,
+        taskKey:    task?.key,
+        title:      task?.title,
+        column:     task?.column,
+        taskType:   task?.taskType || null,
+        subtasks:   (task?.subtasks || []).length,
+        kitApplied,
+        nextStep: task?._id
+          ? [
+              `1. Call remember(taskId="${task._id}", key, value) for each fact in agentConfigAnalysis.rememberFacts.`,
+              `2. Call log_session_event(taskId="${task._id}", type="info", name="task-created", summary="Codebase scouted, kit configured").`,
+              `3. Call kickoff_task(taskId="${task._id}", confirmed=false) — read the plan and check local git state.`,
+              `4. Call submit_task_for_approval(taskId="${task._id}", summary="<3-8 sentences>", reviewerId="<admin id>").`,
+              `5. After approval: call kickoff_task(taskId="${task._id}", confirmed=true, agentRole="builder", files=[...]).`,
+            ].join('\n')
           : null,
-        message: `Task ${task?.key} created and ready to kick off.`,
+        message: `Task ${task?.key} created${kitApplied?.applied ? ' with kit overrides applied' : ''}. Follow nextStep — do NOT branch until the plan is approved.`,
       })
     }
   )
@@ -1912,16 +2060,45 @@ Returns systemPrompt ready to use as a Claude system prompt.`,
         } catch { /* non-fatal */ }
       }
 
-      // Suggest relevant skills based on role and available project skills
-      // Respects project-level enabled + task-level agentKitOverrides
+      // Filter skills to only those relevant to this role and task type.
+      // An agent should NOT load every project skill — only what it needs for this specific task.
       const allProjectSkills = ctx.project?.agentConfig?.skills || []
       const taskSkillOverrides = ctx.task?.agentKitOverrides?.skills || {}
-      const availableSkills = allProjectSkills.filter(s => {
+      const enabledSkills = allProjectSkills.filter(s => {
         const taskOverride = taskSkillOverrides[s.name]
         return taskOverride !== undefined ? taskOverride : s.enabled !== false
       })
-      const suggestedSkills = availableSkills.length > 0
-        ? availableSkills.map(s => ({
+
+      // Role-based relevance filter: each role only gets skills that match its job
+      const ROLE_SKILL_KEYWORDS = {
+        builder:     ['test', 'run', 'build', 'lint', 'commit', 'style', 'deploy', 'migration', 'seed'],
+        scout:       ['scout', 'codebase', 'explore', 'map', 'analyze', 'read'],
+        reviewer:    ['review', 'security', 'audit', 'test', 'quality'],
+        coordinator: ['decompose', 'plan', 'coordinate', 'parallel'],
+      }
+      const roleKeywords = effectiveRole ? (ROLE_SKILL_KEYWORDS[effectiveRole] || []) : []
+
+      // Also use the task type's suggestedSkills list for relevance
+      const taskTypeSkills = (() => {
+        try {
+          const taskType = ctx.task?.taskType || 'feature'
+          const cfg = TASK_TYPES?.[taskType]
+          return cfg?.suggestedSkills || []
+        } catch { return [] }
+      })()
+
+      const relevantSkills = enabledSkills.filter(s => {
+        // Always include explicitly overridden-true skills
+        if (taskSkillOverrides[s.name] === true) return true
+        // Include if skill name matches task type's suggested list
+        if (taskTypeSkills.includes(s.name)) return true
+        // Include if skill name/description matches role keywords
+        const haystack = `${s.name} ${s.description || ''}`.toLowerCase()
+        return roleKeywords.some(kw => haystack.includes(kw))
+      })
+
+      const suggestedSkills = relevantSkills.length > 0
+        ? relevantSkills.map(s => ({
             name: s.name,
             description: s.description,
             path: `.cursor/skills/${s.name}.md`,
@@ -1943,7 +2120,12 @@ Returns systemPrompt ready to use as a Claude system prompt.`,
         suggestedSkills,
         task:            ctx.task,
         project:         ctx.project,
-        usage: 'Use systemPrompt as your Claude system prompt. If allowedTools is set, restrict your MCP tool calls to that list. Read and follow each skill in suggestedSkills before starting work.',
+        usage: [
+          'Use systemPrompt as your Claude system prompt.',
+          'If allowedTools is set, restrict your MCP tool calls to that list.',
+          'Read ONLY the skills listed in suggestedSkills — they are filtered for your role and task type.',
+          'After the task is done (park_task or raise_pr), the skill files are automatically deleted from .cursor/skills/.',
+        ].join(' '),
       })
     }
   )
@@ -3669,6 +3851,43 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       const subtasksDone  = subtasks.filter(s => s.done).length
       const subtasksTotal = subtasks.length
 
+      // ── Gather local git state (used in both preview and confirmed path) ────────
+      let localGitState = null
+      {
+        const pCwd  = repoPath || process.cwd()
+        const pRoot = findRepoRoot(pCwd)
+        if (pRoot) {
+          try {
+            const porcelain    = runGit('status --porcelain=v1', pRoot)
+            const { localState, modified, staged, unstaged, untracked } = parseGitStatus(porcelain)
+            const currentBranch = runGit('branch --show-current', pRoot).trim()
+
+            // Detect default branch (main / master)
+            let defaultBranch = 'main'
+            try {
+              defaultBranch = runGit('symbolic-ref refs/remotes/origin/HEAD', pRoot).trim().replace('refs/remotes/origin/', '')
+            } catch { /* no remote HEAD — stay with 'main' */ }
+
+            // How far behind is the current branch from origin/<default>?
+            let mainBehindBy = 0
+            try {
+              runGit('fetch origin --quiet', pRoot)
+              mainBehindBy = parseInt(runGit(`rev-list HEAD..origin/${defaultBranch} --count`, pRoot).trim(), 10) || 0
+            } catch { /* no remote or network — non-fatal */ }
+
+            localGitState = {
+              repoRoot:     pRoot,
+              currentBranch,
+              defaultBranch,
+              localState,   // 'clean' | 'modified' | 'untracked'
+              modifiedFiles: modified,
+              untrackedFiles: untracked,
+              mainBehindBy,
+            }
+          } catch { /* git not available or not a git repo — non-fatal */ }
+        }
+      }
+
       // ── Preview: show the full plan before touching anything ──
       const pendingApv = (task.approvals || []).find(a => a.state === 'pending') || null
       const hasApprovedApv = (task.approvals || []).some(a => a.state === 'approved')
@@ -3887,10 +4106,24 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
             claimedFiles:     task.claimedFiles || [],
             agentRole:        task.agentRole || null,
           },
+          localGitState: localGitState ? {
+            currentBranch:  localGitState.currentBranch,
+            status:         localGitState.localState,
+            modifiedFiles:  localGitState.modifiedFiles,
+            untrackedFiles: localGitState.untrackedFiles,
+            mainBehindBy:   localGitState.mainBehindBy,
+            ...(localGitState.localState === 'modified' && {
+              warning: `⚠️  You have ${localGitState.modifiedFiles.length} uncommitted change(s) on "${localGitState.currentBranch}". Commit or stash before starting a new task to avoid cross-task pollution.`,
+              suggestedFix: `git stash push -m "wip: before starting ${task.key}"`,
+            }),
+            ...(localGitState.mainBehindBy > 0 && {
+              mainWarning: `⚠️  Your workspace is ${localGitState.mainBehindBy} commit(s) behind origin/${localGitState.defaultBranch}. Run: git pull origin ${localGitState.defaultBranch} before creating a branch.`,
+            }),
+          } : null,
           requiresConfirmation: true,
           message: approvalBlocks
             ? `Read the plan above, then follow workflowRoadmap — approval is required before you can branch and start coding.`
-            : `Read the implementation plan above carefully, then call kickoff_task again with confirmed=true.`,
+            : `Read the implementation plan above carefully, resolve any localGitState warnings, then call kickoff_task again with confirmed=true.`,
         })
       }
 
@@ -3948,28 +4181,39 @@ Use this when a developer says "start task", "brief me on", or "what do I need t
       }
 
       // ── #1 Preflight: check dirty tree before writing cursor rules / moving task ──
-      {
-        const pCwd  = repoPath || process.cwd()
-        const pRoot = findRepoRoot(pCwd)
-        if (pRoot) {
-          try {
-            const porcelain = runGit('status --porcelain=v1', pRoot)
-            const { localState, modified } = parseGitStatus(porcelain)
-            const currentBranchNow = runGit('branch --show-current', pRoot).trim()
-            if (localState === 'modified' && task.github?.headBranch && currentBranchNow !== task.github.headBranch) {
-              return text({
-                blocked:      true,
-                reason:       `You are on "${currentBranchNow}" with ${modified.length} modified file(s), but this task's branch is "${task.github.headBranch}".`,
-                modifiedFiles: modified,
-                choices: {
-                  stash:   `git stash push -m "wip: before kickoff ${task.key} on ${currentBranchNow}"`,
-                  autoSwitch: `Switch to ${task.github.headBranch}: git stash && git checkout ${task.github.headBranch} && git stash pop`,
-                  cancel:  'Review your changes first, then retry kickoff_task',
-                },
-                message: 'Resolve the working tree before kicking off this task to avoid cross-task pollution.',
-              })
-            }
-          } catch { /* non-fatal */ }
+      // Use the git state we already gathered above; re-check if not available.
+      if (localGitState?.localState === 'modified') {
+        const { currentBranch, modifiedFiles } = localGitState
+        const taskBranch = task.github?.headBranch
+
+        if (taskBranch && currentBranch !== taskBranch) {
+          // On the wrong branch — stash and switch, or cancel
+          return text({
+            blocked:       true,
+            reason:        `You are on "${currentBranch}" with ${modifiedFiles.length} uncommitted change(s), but this task's branch is "${taskBranch}".`,
+            modifiedFiles,
+            choices: {
+              stash:      `git stash push -m "wip: before kickoff ${task.key} on ${currentBranch}"`,
+              autoSwitch: `git stash && git checkout ${taskBranch} && git stash pop`,
+              cancel:     'Review your changes first, then retry kickoff_task',
+            },
+            message: '⛔ Resolve the working tree before kicking off this task to avoid cross-task pollution.',
+          })
+        }
+
+        if (!taskBranch) {
+          // First-time kickoff — uncommitted changes risk bleeding into the new branch
+          return text({
+            blocked:       true,
+            reason:        `You have ${modifiedFiles.length} uncommitted change(s) on "${currentBranch}". Starting a new task from a dirty tree would carry these changes into the new branch.`,
+            modifiedFiles,
+            choices: {
+              stash:  `git stash push -m "wip: before starting ${task.key}"`,
+              commit: 'git add -p && git commit -m "wip: save changes before new task"',
+              cancel: 'Review your changes, then retry kickoff_task',
+            },
+            message: '⛔ Commit or stash your changes before creating a new task branch.',
+          })
         }
       }
 
@@ -4145,6 +4389,26 @@ After \`request_human_input\`: STOP, show the question in chat, wait for reply,
       }
       api.patch(`/api/tasks/${taskId}`, workspacePatch).catch(() => {/* non-fatal */})
 
+      // Auto-log every skill / rule / agent written to the session timeline
+      // so the Session tab always shows what got injected at kickoff.
+      if (workspaceResult?.written?.length) {
+        const repoRoot = workspaceResult.repoRoot || ''
+        for (const filePath of workspaceResult.written) {
+          const rel  = filePath.replace(repoRoot, '').replace(/^\//, '')
+          const name = rel.replace(/^\.cursor\/(skills|rules|agents|commands)\//, '').replace(/\.(md|mdc)$/, '')
+          const type = rel.includes('/skills/')   ? 'skill'
+                     : rel.includes('/rules/')    ? 'rule'
+                     : rel.includes('/agents/')   ? 'subagent'
+                     : 'info'
+          api.post(`/api/tasks/${taskId}/session/log`, {
+            type,
+            name,
+            role:    agentRole || null,
+            summary: `${type === 'skill' ? '📖' : type === 'rule' ? '📏' : type === 'subagent' ? '🤖' : 'ℹ️'} Injected at kickoff: ${rel}`,
+          }).catch(() => {/* non-fatal */})
+        }
+      }
+
       // Write .internaltool-active-task so the Claude Code hook knows a task is active
       try {
         writeFileSync(
@@ -4399,18 +4663,40 @@ How to determine status:
 
   server.tool(
     'submit_task_for_approval',
-    'Create and submit a new approval request on a task. Each request has its own title, plan/readme, and reviewer. Only one request can be pending at a time.',
+    `Create and immediately submit an approval request so a human reviewer can approve the plan before any branch or code is created.
+
+This is a single atomic operation — it creates the approval draft and submits it in one step.
+Only one approval can be pending at a time. Returns blocked=true if another is already pending.
+
+IMPORTANT — what to write in "summary":
+- Write a SHORT, new approval request (3–8 sentences). Do NOT copy the task readmeMarkdown verbatim.
+- The reviewer already has access to the full plan. Your job is to write a concise summary: what will change, why, and what the key risks are.
+- Example: "This adds Redis caching to the product list endpoint. It will reduce DB load by ~60% during peak hours. Key risk: cache invalidation on product updates — handled by clearing the cache key on every product.save()."`,
     {
       taskId:     z.string().describe("Task's MongoDB ObjectId"),
-      title:      z.string().describe('Short title for this approval request, e.g. "Experiment: Add caching layer"'),
-      readme:     z.string().describe('The plan/markdown describing what you want to do and why (min 80 chars)'),
-      reviewerId: z.string().describe('User ID of the reviewer'),
+      title:      z.string().describe('Short title for this approval request, e.g. "Plan: Add Redis caching to product list"'),
+      summary:    z.string().describe('A 3–8 sentence approval summary (NOT the full README). Describe: what changes, why, and key risks. The reviewer will read the full plan separately.'),
+      reviewerId: z.string().describe('User ID of the reviewer (admin or project lead)'),
     },
-    async ({ taskId, title, readme, reviewerId }) => {
-      // Gate: block if latest test run is failing
+    async ({ taskId, title, summary, reviewerId }) => {
+      // Gate: block if another approval is already pending
       const taskRes = await api.get(`/api/tasks/${taskId}`)
       if (taskRes?.success) {
-        const latestRun = taskRes.data?.task?.testRuns?.[0]
+        const task = taskRes.data?.task
+        const alreadyPending = (task?.approvals || []).find(a => a.state === 'pending')
+        if (alreadyPending) {
+          return text({
+            blocked: true,
+            reason:  'An approval is already pending review.',
+            pendingApproval: {
+              title: alreadyPending.title,
+              requestedAt: alreadyPending.requestedAt,
+            },
+            message: 'Wait for the reviewer to decide on the existing request, or ask them to reject it first.',
+          })
+        }
+        // Gate: block if latest test run is failing
+        const latestRun = task?.testRuns?.[0]
         if (latestRun && latestRun.status === 'failing') {
           return text({
             blocked: true,
@@ -4426,7 +4712,33 @@ How to determine status:
           })
         }
       }
-      return call(() => api.post(`/api/tasks/${taskId}/approvals`, { title, readme, reviewerId }))
+
+      // Step 1: create draft
+      const createRes = await api.post(`/api/tasks/${taskId}/approvals`, { title, readme: summary })
+      if (!createRes?.success) return errorText(createRes?.message || 'Could not create approval draft')
+      const freshTask = createRes.data?.task
+      const newApproval = (freshTask?.approvals || []).find(a => a.state === 'none' && a.title === title)
+      if (!newApproval?._id) return errorText('Approval created but could not find its ID — check the task approvals tab')
+
+      // Step 2: immediately submit for review
+      const submitRes = await api.post(`/api/tasks/${taskId}/approvals/${newApproval._id}/submit`, { reviewerId })
+      if (!submitRes?.success) {
+        return text({
+          draftCreated: true,
+          approvalId:   newApproval._id,
+          submitFailed: true,
+          reason:       submitRes?.message || 'Draft created but submit step failed',
+          message:      'The approval draft was created but could not be submitted automatically. Open the task → Approval tab → click "Submit for review" manually.',
+        })
+      }
+      return text({
+        submitted:  true,
+        approvalId: newApproval._id,
+        title,
+        state:      'pending',
+        message:    `Approval request submitted. The reviewer will be notified. Do NOT start coding or create a branch until they approve.`,
+        nextStep:   `Wait for decide_task_approval to return decision="approve". Then call create_branch.`,
+      })
     }
   )
 
@@ -5129,6 +5441,29 @@ function writeCursorWorkspace(task, projectAgentConfig, startPath) {
     mkdirSync(commandsDir, { recursive: true })
     mkdirSync(rulesDir,    { recursive: true })
 
+    // ── Ensure generated AI files are NOT committed by the developer ────────────
+    // These are runtime files — they change per task and per agent session.
+    // They belong in the developer's local env, not in git history.
+    const gitignorePath = join(repoRoot, '.gitignore')
+    const AI_GITIGNORE_ENTRIES = [
+      '# InternalTool AI workspace — auto-generated, do not commit',
+      '.cursor/agents/',
+      '.cursor/skills/',
+      '.cursor/commands/',
+      '.cursor/rules/',
+      '.claude/',
+      '.internaltool-active-task',
+    ]
+    try {
+      let existing = ''
+      if (existsSync(gitignorePath)) existing = readFileSync(gitignorePath, 'utf8')
+      const missing = AI_GITIGNORE_ENTRIES.filter(e => e.startsWith('#') ? false : !existing.includes(e))
+      if (missing.length > 0) {
+        const toAppend = '\n' + AI_GITIGNORE_ENTRIES[0] + '\n' + missing.join('\n') + '\n'
+        writeFileSync(gitignorePath, existing + toAppend, 'utf8')
+      }
+    } catch { /* non-fatal — gitignore update is best-effort */ }
+
     const written = []
 
     // ── 1. Project-level rules from DB → .cursor/rules/<name>.mdc ─────────────
@@ -5394,23 +5729,41 @@ log_session_event(type="info", name="conflict-resolved", summary="<what you merg
 
 /**
  * Delete task-specific workspace files written at kickoff.
- * Project-level rules (.cursor/rules/<project-rule>.mdc) and skills are kept.
- * Only the active-agent and start-task command are removed (they are task-scoped).
+ * Removes: active-agent.md, start-task.md command, and ALL skill files in .cursor/skills/.
+ * Project-level rules (.cursor/rules/*.mdc) are kept — they are curated by the admin, not generated per task.
  */
 function deleteCursorWorkspace(role, startPath) {
   const deleted = []
   try {
     const repoRoot = findRepoRoot(startPath)
     if (!repoRoot) return deleted
-    const toDelete = [
+
+    // Always-delete: task-scoped agent and command files
+    const alwaysDelete = [
       join(repoRoot, '.cursor', 'agents', 'active-agent.md'),
       join(repoRoot, '.cursor', 'commands', 'start-task.md'),
     ]
-    for (const f of toDelete) {
+    for (const f of alwaysDelete) {
       try {
         if (existsSync(f)) { unlinkSync(f); deleted.push(f) }
       } catch { /* non-fatal */ }
     }
+
+    // Delete all skill files — they are fetched fresh on every kickoff
+    // based on role and task type. Keeping stale skills causes context bloat.
+    const skillsDir = join(repoRoot, '.cursor', 'skills')
+    if (existsSync(skillsDir)) {
+      try {
+        const skillFiles = readdirSync(skillsDir).filter(f => f.endsWith('.md'))
+        for (const f of skillFiles) {
+          try {
+            const fullPath = join(skillsDir, f)
+            unlinkSync(fullPath)
+            deleted.push(fullPath)
+          } catch { /* non-fatal */ }
+        }
+      } catch { /* non-fatal */ }
+    }
   } catch { /* non-fatal */ }
   return deleted
 }
@@ -6065,14 +6418,13 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
       const task = taskRes.data.task
 
       // ── Approval gate check ───────────────────────────────────────────────────
-      // The server blocks non-admins from moving todo → in_progress without approval.
-      // Detect this early and guide the developer instead of failing silently after branch creation.
+      // Block branch creation (at both confirmed=false AND confirmed=true) until the plan is approved.
       const pendingApv2 = (task.approvals || []).find(a => a.state === 'pending') || null
       const hasApprovedApv2 = (task.approvals || []).some(a => a.state === 'approved')
       const approvalState = pendingApv2 ? 'pending' : hasApprovedApv2 ? 'approved' : 'none'
       const PLANNING_COLS = ['backlog', 'todo']
       const needsApproval = PLANNING_COLS.includes(task.column) && !hasApprovedApv2
-      if (needsApproval && !confirmed) {
+      if (needsApproval) {
         const isFix2 = /\b(fix|bug|hotfix|patch)\b/i.test(task.title + ' ' + (task.description || ''))
         const slug2 = task.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 35)
         const previewBranch = `${isFix2 ? 'fix' : 'feature'}/${task.key.toLowerCase()}-${slug2}`
@@ -6080,16 +6432,16 @@ If you have uncommitted tracked changes, it will tell you exactly what to do bef
           blocked: true,
           reason: 'approval_required',
           task:   { key: task.key, title: task.title, column: task.column, approvalState },
-          message: `The task's implementation plan (README) must be approved before creating a branch and moving to In progress.`,
+          message: `⛔ The plan must be approved before creating a branch. Do NOT code until the reviewer approves.`,
           approvalStatus: approvalState === 'pending'
-            ? `Plan is already submitted and waiting for reviewer approval. Once approved, call create_branch again.`
+            ? `Plan is submitted and waiting for reviewer approval. Once approved, call create_branch again.`
             : `Plan has not been submitted for review yet.`,
           nextSteps: approvalState === 'pending'
-            ? [`Wait for the reviewer to approve, then call create_branch with taskId="${taskId}"`]
+            ? [`Wait for decide_task_approval to return decision="approve", then call create_branch with taskId="${taskId}"`]
             : [
-                `1. Make sure the README / implementation plan is written on the task (use update_task with readmeMarkdown if needed)`,
-                `2. Call submit_task_for_approval with taskId="${taskId}" and the reviewerId of your project lead`,
-                `3. Once approved, call create_branch again — it will create "${previewBranch}" and move the task to In progress automatically`,
+                `1. Write the implementation plan: call update_task with readmeMarkdown if not already written`,
+                `2. Call submit_task_for_approval with taskId="${taskId}", summary="<3-8 sentence summary>", reviewerId="<admin user id>"`,
+                `3. Once approved: call create_branch — it will create "${previewBranch}" and move the task to In progress`,
               ],
         })
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "internaltool-mcp",
-  "version": "1.6.42",
+  "version": "1.6.45",
   "description": "MCP server for InternalTool — connect AI assistants (Claude Code, Cursor) to your project and task management platform",
   "type": "module",
   "main": "index.js",