@damper/mcp 0.8.2 → 0.8.4

package/dist/formatters.d.ts

@@ -4,6 +4,11 @@
  * Extracted for testability - these pure functions format API responses
  * into user-friendly text output.
  */
+export interface SelfAssessment {
+    missingContext?: string[];
+    toolIssues?: string[];
+    processGaps?: string[];
+}
 export interface StartTaskResult {
     id: string;
     status: string;
@@ -39,11 +44,16 @@ export interface AbandonTaskResult {
  * Format start_task response
  */
 export declare function formatStartTaskResponse(result: StartTaskResult): string;
+/**
+ * Format self-assessment follow-up actions.
+ * Guides the agent to propose improvements to the user with rationale.
+ */
+export declare function formatSelfAssessmentActions(assessment: SelfAssessment): string;
 /**
  * Format complete_task response
  */
-export declare function formatCompleteTaskResponse(result: CompleteTaskResult): string;
+export declare function formatCompleteTaskResponse(result: CompleteTaskResult, assessment?: SelfAssessment): string;
 /**
  * Format abandon_task response
  */
-export declare function formatAbandonTaskResponse(result: AbandonTaskResult, hasSummary: boolean): string;
+export declare function formatAbandonTaskResponse(result: AbandonTaskResult, hasSummary: boolean, assessment?: SelfAssessment): string;

package/dist/formatters.js

@@ -52,18 +52,67 @@ export function formatStartTaskResponse(result) {
     lines.push('1. `add_note`: "Session started: <goal>"');
     lines.push('2. Work: use `add_commit` for commits, `add_note` for decisions');
     lines.push('3. `add_note`: "Session end: <summary>"');
-    lines.push('4. `complete_task` (with `confirmations` if checklist exists) or `abandon_task`');
+    lines.push('4. `complete_task` (with `confirmations` and `selfAssessment`) or `abandon_task`');
+    return lines.join('\n');
+}
+/**
+ * Format self-assessment follow-up actions.
+ * Guides the agent to propose improvements to the user with rationale.
+ */
+export function formatSelfAssessmentActions(assessment) {
+    const lines = [];
+    const hasContent = (assessment.missingContext?.length ?? 0) > 0
+        || (assessment.toolIssues?.length ?? 0) > 0
+        || (assessment.processGaps?.length ?? 0) > 0;
+    if (!hasContent)
+        return '';
+    lines.push('\n🔍 **Self-Assessment — propose these improvements to the user:**');
+    lines.push('Explain each finding briefly and why fixing it helps future tasks. Ask for approval before acting.');
+    if (assessment.missingContext && assessment.missingContext.length > 0) {
+        lines.push('\n**Missing project context:**');
+        for (const item of assessment.missingContext) {
+            lines.push(`  • ${item}`);
+        }
+        lines.push('→ Propose calling `update_context_section` to document these — explain that future agents will waste time rediscovering the same things.');
+    }
+    if (assessment.toolIssues && assessment.toolIssues.length > 0) {
+        lines.push('\n**Tool/workflow issues:**');
+        for (const item of assessment.toolIssues) {
+            lines.push(`  • ${item}`);
+        }
+        lines.push('→ Propose calling `report_issue` for each — explain what went wrong and how it slowed the task.');
+    }
+    if (assessment.processGaps && assessment.processGaps.length > 0) {
+        lines.push('\n**Process/spec gaps:**');
+        for (const item of assessment.processGaps) {
+            lines.push(`  • ${item}`);
+        }
+        lines.push('→ Propose `update_context_section` for doc gaps or `report_issue` for tooling problems — explain the friction it caused.');
+    }
     return lines.join('\n');
 }
 /**
  * Format complete_task response
  */
-export function formatCompleteTaskResponse(result) {
+export function formatCompleteTaskResponse(result, assessment) {
     const lines = [`✅ Completed ${result.id}`];
-    lines.push('\n---');
-    lines.push('**📚 Before you finish:**');
-    lines.push('Did you learn something about this codebase that would help future agents?');
-    lines.push('→ Use `update_context_section` to share architecture, patterns, or gotchas.');
+    // Self-assessment follow-up actions (shown first if provided)
+    if (assessment) {
+        const actions = formatSelfAssessmentActions(assessment);
+        if (actions) {
+            lines.push(actions);
+        }
+    }
+    if (!assessment) {
+        // No assessment provided — nudge the agent to reflect
+        lines.push('\n---');
+        lines.push('**🔍 Before you finish — quick self-assessment:**');
+        lines.push('Reflect on your session. If you encountered any of these, propose improvements to the user:');
+        lines.push('• Missing project docs → offer to call `update_context_section`');
+        lines.push('• Confusing tools → offer to call `report_issue`');
+        lines.push('• Spec/process gaps → offer to update docs or report');
+        lines.push('Explain briefly why each improvement would help future tasks.');
+    }
     if (result.documentation) {
         if (result.documentation.affectedSections?.length > 0) {
             lines.push(`\nSections that may need updates: ${result.documentation.affectedSections.join(', ')}`);
@@ -77,11 +126,26 @@ export function formatCompleteTaskResponse(result) {
 /**
  * Format abandon_task response
  */
-export function formatAbandonTaskResponse(result, hasSummary) {
+export function formatAbandonTaskResponse(result, hasSummary, assessment) {
     const lines = [`⏸️ Abandoned ${result.id}: ${result.message}`];
     if (!hasSummary) {
         lines.push('\n⚠️ Tip: Include a summary next time for better handoff.');
     }
     lines.push('\n💡 Task returned to "planned". Notes preserved for next agent.');
+    // Self-assessment follow-up actions
+    if (assessment) {
+        const actions = formatSelfAssessmentActions(assessment);
+        if (actions) {
+            lines.push(actions);
+        }
+    }
+    if (!assessment) {
+        lines.push('\n---');
+        lines.push('**🔍 Before you finish — quick self-assessment:**');
+        lines.push('Something caused this task to be abandoned. Propose improvements to the user:');
+        lines.push('• Missing project docs that would have helped → offer to call `update_context_section`');
+        lines.push('• Tool issues that blocked progress → offer to call `report_issue`');
+        lines.push('Explain briefly why each fix would help the next agent pick this up smoothly.');
+    }
     return lines.join('\n');
 }

package/dist/index.js

@@ -269,8 +269,10 @@ server.registerTool('update_task', {
         'Useful for refining task details as you learn more about the work.',
     inputSchema: z.object({
         taskId: z.string().describe('Task ID'),
-        title: z.string().optional().describe('Task title'),
-        description: z.string().optional().describe('Task description (shown on public roadmap)'),
+        title: z.string().optional().describe('Task title (max 60 chars, sentence case, no trailing period). Verb prefix: ' +
+            'bug → "Fix …", feature → "Add …", improvement → "Improve …", task → "Set up …" / "Update …"'),
+        description: z.string().optional().describe('Task description (shown on public roadmap). Write for end users: 1-3 sentences on what changes and why it matters. ' +
+            'No code references, file paths, or jargon.'),
         implementationPlan: z.string().optional().describe('Implementation plan (markdown, internal only - never shown publicly)'),
         priority: z.enum(['high', 'medium', 'low']).nullable().optional().describe('Task priority'),
         effort: z.enum(['xs', 's', 'm', 'l', 'xl']).nullable().optional().describe('Estimated effort'),
@@ -351,9 +353,11 @@ server.registerTool('create_task', {
     title: 'Create Task',
     description: 'Create a new roadmap task. Use for importing from TODO files or creating work items.',
     inputSchema: z.object({
-        title: z.string().describe('Task title. Use verb prefix matching the type: ' +
-            'bug → "Fix …", feature → "Add …", improvement → "Improve …", task → "Set up …" / "Update …"'),
-        description: z.string().optional().describe('Task description (shown on public roadmap)'),
+        title: z.string().describe('Task title (max 60 chars, sentence case, no trailing period). Use verb prefix matching the type: ' +
+            'bug → "Fix …", feature → "Add …", improvement → "Improve …", task → "Set up …" / "Update …". ' +
+            'E.g., "Add dark mode support", "Fix login timeout on slow connections"'),
+        description: z.string().optional().describe('Task description (shown on public roadmap). Write for end users: 1-3 sentences on what changes and why it matters. ' +
+            'No code references, file paths, or jargon.'),
         type: z.enum(['bug', 'feature', 'improvement', 'task']).optional().describe('Task type (default: feature)'),
         status: z.enum(['planned', 'in_progress', 'done']).optional(),
         priority: z.enum(['high', 'medium', 'low']).optional().describe('Task priority'),
@@ -498,7 +502,7 @@ server.registerTool('add_commit', {
     inputSchema: z.object({
         taskId: z.string(),
         hash: z.string().describe('Commit hash (short or full)'),
-        message: z.string().describe('Commit message'),
+        message: z.string().describe('Commit message in conventional commits format: type(scope): description. E.g., "feat(auth): add OAuth login"'),
     }),
     outputSchema: z.object({
         taskId: z.string(),
@@ -524,7 +528,7 @@ server.registerTool('create_subtask', {
     description: 'Add a new subtask to a task. Useful for breaking down work into smaller steps.',
     inputSchema: z.object({
         taskId: z.string().describe('Task ID'),
-        title: z.string().describe('Subtask title'),
+        title: z.string().describe('Subtask title — short imperative phrase, e.g., "Add validation to login form"'),
     }),
     outputSchema: z.object({
         taskId: z.string(),
@@ -589,6 +593,12 @@ server.registerTool('update_subtask', {
         },
     };
 });
+// Self-assessment schema for end-of-task reflection
+const SelfAssessmentSchema = z.object({
+    missingContext: z.array(z.string()).optional().describe('Project knowledge that was missing or wrong — things you had to figure out that should be documented for future agents'),
+    toolIssues: z.array(z.string()).optional().describe('MCP tools or workflow steps that were confusing, broken, or could be improved'),
+    processGaps: z.array(z.string()).optional().describe('Gaps in specs, checklists, or conventions that caused friction or mistakes'),
+});
 // Documentation reminder schema for complete_task response
 const DocumentationSchema = z.object({
     hasContext: z.boolean(),
@@ -602,6 +612,8 @@ server.registerTool('complete_task', {
         '**Before calling:**\n' +
         '1. Push all commits\n' +
         '2. Check if project context docs need updating\n\n' +
+        '**Self-assessment:** Reflect on your session — what project knowledge was missing, what tools were confusing, ' +
+        'what process gaps caused friction. If you identify improvements, propose them to the user with a brief explanation.\n\n' +
         '**Completion checklist:** If the project has a completion checklist (shown in `start_task` response), ' +
         'you MUST pass `confirmations` — an array of `{item, evidence}` objects. Each confirmation needs the checklist item text ' +
         'and concrete evidence proving you verified it (e.g., test output, build log snippet). ' +
@@ -610,7 +622,9 @@ server.registerTool('complete_task', {
         'Returns documentation update suggestions.',
     inputSchema: z.object({
         taskId: z.string(),
-        summary: z.string().describe('Brief one-line summary of what was done'),
+        summary: z.string().describe('Brief one-line summary of what was done, written for end users. Focus on the outcome, not the implementation.'),
+        selfAssessment: SelfAssessmentSchema.optional().describe('Reflect on your session: what went well, what knowledge was missing, what caused friction. ' +
+            'Be honest — this drives project improvements.'),
         commits: z.array(z.object({
             hash: z.string().describe('Commit hash (short or full)'),
             message: z.string().describe('Commit message'),
@@ -631,11 +645,38 @@ server.registerTool('complete_task', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ taskId, summary, commits, confirmations }) => {
+}, async ({ taskId, summary, selfAssessment, commits, confirmations }) => {
     try {
         const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary, commits, confirmations });
+        // Log self-assessment as a structured note if provided
+        if (selfAssessment) {
+            const assessmentLines = ['Self-Assessment:'];
+            if (selfAssessment.missingContext?.length) {
+                assessmentLines.push('Missing context:');
+                for (const item of selfAssessment.missingContext)
+                    assessmentLines.push(`  - ${item}`);
+            }
+            if (selfAssessment.toolIssues?.length) {
+                assessmentLines.push('Tool issues:');
+                for (const item of selfAssessment.toolIssues)
+                    assessmentLines.push(`  - ${item}`);
+            }
+            if (selfAssessment.processGaps?.length) {
+                assessmentLines.push('Process gaps:');
+                for (const item of selfAssessment.processGaps)
+                    assessmentLines.push(`  - ${item}`);
+            }
+            if (assessmentLines.length > 1) {
+                try {
+                    await api('POST', `/api/agent/tasks/${taskId}/notes`, { note: assessmentLines.join('\n') });
+                }
+                catch {
+                    // Don't fail completion if note logging fails
+                }
+            }
+        }
         return {
-            content: [{ type: 'text', text: formatCompleteTaskResponse(result) }],
+            content: [{ type: 'text', text: formatCompleteTaskResponse(result, selfAssessment) }],
             structuredContent: result,
         };
     }
@@ -675,10 +716,14 @@ server.registerTool('abandon_task', {
     description: 'Release lock and return task to planned status. Use when stopping work.\n\n' +
         '**Before calling:**\n' +
         '1. Push any WIP commits\n\n' +
-        '**Summary parameter:** What was done, what remains, blockers. Helps the next agent.',
+        '**Summary parameter:** What was done, what remains, blockers. Helps the next agent.\n\n' +
+        '**Self-assessment:** Especially important when abandoning — reflect on what blocked you ' +
+        'or what knowledge was missing so the next agent has a smoother experience.',
     inputSchema: z.object({
         taskId: z.string(),
         summary: z.string().optional().describe('Handoff summary: what was done, what remains, any blockers'),
+        selfAssessment: SelfAssessmentSchema.optional().describe('Reflect on your session: what went well, what knowledge was missing, what caused friction. ' +
+            'Be honest — this drives project improvements.'),
     }),
     outputSchema: z.object({
         id: z.string(),
@@ -691,10 +736,37 @@ server.registerTool('abandon_task', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ taskId, summary }) => {
+}, async ({ taskId, summary, selfAssessment }) => {
     const result = await api('POST', `/api/agent/tasks/${taskId}/abandon`, summary ? { summary } : undefined);
+    // Log self-assessment as a structured note if provided
+    if (selfAssessment) {
+        const assessmentLines = ['Self-Assessment (abandoned):'];
+        if (selfAssessment.missingContext?.length) {
+            assessmentLines.push('Missing context:');
+            for (const item of selfAssessment.missingContext)
+                assessmentLines.push(`  - ${item}`);
+        }
+        if (selfAssessment.toolIssues?.length) {
+            assessmentLines.push('Tool issues:');
+            for (const item of selfAssessment.toolIssues)
+                assessmentLines.push(`  - ${item}`);
+        }
+        if (selfAssessment.processGaps?.length) {
+            assessmentLines.push('Process gaps:');
+            for (const item of selfAssessment.processGaps)
+                assessmentLines.push(`  - ${item}`);
+        }
+        if (assessmentLines.length > 1) {
+            try {
+                await api('POST', `/api/agent/tasks/${taskId}/notes`, { note: assessmentLines.join('\n') });
+            }
+            catch {
+                // Don't fail abandonment if note logging fails
+            }
+        }
+    }
     return {
-        content: [{ type: 'text', text: formatAbandonTaskResponse(result, !!summary) }],
+        content: [{ type: 'text', text: formatAbandonTaskResponse(result, !!summary, selfAssessment) }],
         structuredContent: result,
     };
 });
@@ -744,7 +816,7 @@ server.registerTool('get_agent_instructions', {
         openWorldHint: false,
     },
 }, async ({ format = 'section' }) => {
-    const lastModified = '2026-02-08';
+    const lastModified = '2026-02-10';
     const section = `## Task Management with Damper MCP
 
 > Last updated: ${lastModified}
@@ -787,7 +859,49 @@ This project uses Damper MCP for task tracking. **You MUST follow this workflow.
   2. **Abandon and hand off** - Call \`abandon_task\` with a detailed handoff summary for the next agent.
 - NEVER leave a started task without completing or abandoning it
 - If the project has a **completion checklist** (shown in \`start_task\` response), you MUST pass all items as \`confirmations\` when calling \`complete_task\`
-- If you learned something about the codebase, consider updating project context
+- **Self-assessment:** Include \`selfAssessment\` when calling \`complete_task\` or \`abandon_task\`. Reflect honestly on:
+  - \`missingContext\` — What project knowledge was missing or wrong?
+  - \`toolIssues\` — Which tools or workflow steps were confusing or broken?
+  - \`processGaps\` — What specs or conventions were missing?
+  If you identify improvements, **propose them to the user** — explain briefly what you found and why fixing it helps future tasks. Only act after the user approves.
+
+### Content Style Guide
+
+All content you generate — titles, descriptions, changelogs, notes — should follow these conventions for consistency.
+
+**Task titles:**
+- Imperative verb prefix matching type: bug → "Fix …", feature → "Add …", improvement → "Improve …", task → "Set up …" / "Update …"
+- Sentence case after verb (lowercase unless proper noun): "Add dark mode support"
+- Max 60 characters, no trailing period
+- Specific enough to understand without reading the description
+
+**Task descriptions** (shown on public roadmap):
+- Write for end users, not developers — no code references, file paths, or jargon
+- 1-3 sentences explaining what changes and why it matters to users
+- Focus on the user benefit, not implementation details
+
+**Subtask titles:**
+- Short imperative phrase: "Add validation to login form"
+- Specific enough to track independently
+
+**Changelog content:**
+- Write for users who want to know what changed and why they should care
+- Group entries by type: Added, Improved, Fixed
+- Each entry: 1-2 sentences focused on the user-visible change, not the technical approach
+- Use plain language — avoid technical jargon
+
+**Changelog summaries** (max 280 chars):
+- Lead with the most impactful change
+- Conversational tone suitable for social media or email subject
+
+**Commit messages:**
+- Conventional commits format: \`type(scope): description\`
+- Types: feat, fix, refactor, test, docs, chore, style, perf
+- Imperative mood: "add feature" not "added feature"
+
+**Notes:**
+- Prefix with category: "Decision: …", "Blocked: …", "Context: …"
+- Only log non-obvious decisions and blockers — skip routine progress
 
 ### Why This Matters
 - **Project context prevents mistakes** - Contains architecture decisions, gotchas, and patterns
@@ -1731,10 +1845,12 @@ server.registerTool('create_changelog', {
         'Use this to create additional changelogs if needed.',
     inputSchema: z.object({
         title: z.string().describe('Changelog title (e.g., "v2.1.0" or "January 2025 Release")'),
-        content: z.string().optional().describe('Initial changelog content (markdown)'),
+        content: z.string().optional().describe('Changelog content (markdown). Write for users: group by Added/Improved/Fixed, ' +
+            '1-2 sentences per entry focused on user-visible changes. Avoid technical jargon.'),
         version: z.string().optional().describe('Version number'),
         date: z.string().optional().describe('Custom display date (ISO 8601). When set, used for sorting/display instead of publishedAt.'),
-        summary: z.string().max(280).optional().describe('Short summary for social sharing and email subject (max 280 chars)'),
+        summary: z.string().max(280).optional().describe('Short summary for social sharing and email subject (max 280 chars). ' +
+            'Lead with the most impactful change, conversational tone.'),
         status: z.enum(['draft', 'published']).optional().describe('Status (default: draft)'),
     }),
     outputSchema: z.object({
@@ -1766,10 +1882,12 @@ server.registerTool('update_changelog', {
     inputSchema: z.object({
         changelogId: z.string().describe('Changelog ID'),
         title: z.string().optional().describe('New title'),
-        content: z.string().optional().describe('New content (markdown)'),
+        content: z.string().optional().describe('New content (markdown). Write for users: group by Added/Improved/Fixed, ' +
+            '1-2 sentences per entry focused on user-visible changes. Avoid technical jargon.'),
         version: z.string().optional().describe('Version number'),
         date: z.string().optional().describe('Custom display date (ISO 8601). When set, used for sorting/display instead of publishedAt. Pass empty string to clear.'),
-        summary: z.string().max(280).optional().describe('Short summary for social sharing and email subject (max 280 chars)'),
+        summary: z.string().max(280).optional().describe('Short summary for social sharing and email subject (max 280 chars). ' +
+            'Lead with the most impactful change, conversational tone.'),
         status: z.enum(['draft', 'published']).optional().describe('Status'),
     }),
     outputSchema: z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damper/mcp",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "MCP server for Damper task management",
   "author": "Damper <hello@usedamper.com>",
   "repository": {