@waycraft/waypoint-mcp 0.1.0

package/dist/tools/fix.js

@@ -0,0 +1,103 @@
+import { getBaseContext, getArtifact, saveArtifact } from "../context.js";
+export const definition = {
+    name: "waypoint_fix",
+    description: "Targeted bug patches with minimal footprint.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            workspacePath: {
+                type: "string",
+                description: "Absolute path to the workspace root.",
+            },
+            bug: {
+                type: "string",
+                description: "Description of the bug to fix (optional). Omit to review existing fix.md.",
+            },
+        },
+        required: ["workspacePath"],
+    },
+};
+export async function run(args) {
+    const { workspacePath, bug } = args;
+    const ctx = await getBaseContext(workspacePath);
+    const buildArtifact = await getArtifact(workspacePath, "build.md");
+    const goalArtifact = await getArtifact(workspacePath, "goal.md");
+    const existingFix = await getArtifact(workspacePath, "fix.md");
+    if (!bug && !existingFix) {
+        return [
+            "## waypoint_fix — No bug description provided",
+            "",
+            "Call `waypoint_fix` with a `bug` parameter describing the problem.",
+            "Example: _\"Tool returns isError:true when workspacePath has spaces\"_",
+            "",
+            !buildArtifact ? "Run `waypoint_build` first to establish a build baseline." : "",
+        ]
+            .filter(Boolean)
+            .join("\n");
+    }
+    const bugStatement = bug ?? existingFix?.match(/^## Bug\n+(.+)/m)?.[1] ?? "(bug not parsed)";
+    const goalLine = goalArtifact?.match(/^# Goal\n+(.+)/m)?.[1] ?? "(goal not parsed)";
+    const hasBuild = !!buildArtifact;
+    const artifact = [
+        "# Fix",
+        "",
+        `## Bug`,
+        bugStatement,
+        "",
+        `**Goal context:** ${goalLine}`,
+        !hasBuild ? "\n> ⚠️ No build.md found — fix has no established baseline." : "",
+        "",
+        "## Root cause hypothesis",
+        "<!-- What is causing this bug? Be specific. -->",
+        "- ",
+        "",
+        "## Fix approach",
+        "**Principle:** minimal footprint — change only what is necessary to fix this bug.",
+        "",
+        "### AI fix prompt",
+        "```",
+        `Fix the following bug: ${bugStatement}`,
+        "",
+        "Constraints:",
+        "- Change only the code required to fix this specific bug",
+        "- Do not refactor surrounding code",
+        "- Do not add features or improve unrelated behavior",
+        "- Verify the fix does not break adjacent functionality",
+        "```",
+        "",
+        "## Changes made",
+        "<!-- List exact files and lines changed -->",
+        "| File | Line(s) | Change |",
+        "|------|---------|--------|",
+        "| | | |",
+        "",
+        "## Verification",
+        "- [ ] Bug no longer reproduced with original steps",
+        "- [ ] No regressions in adjacent functionality",
+        "- [ ] Fix is the minimum change required",
+        "",
+        `_Generated by waypoint_fix — ${new Date().toISOString()}_`,
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+    await saveArtifact(workspacePath, "fix.md", artifact);
+    return [
+        "## waypoint_fix — Fix guide generated",
+        "",
+        `**Bug:** ${bugStatement}`,
+        !hasBuild ? "\n> No build.md found — fix has no baseline context." : "",
+        "",
+        "### Approach",
+        "- Minimal footprint: only change what fixes this bug",
+        "- AI fix prompt included — paste into Claude Code or Cursor",
+        "- Verification checklist: confirm no regressions",
+        "",
+        "### Artifact saved",
+        "`fix.md` written to `.waypoint/fix.md`.",
+        "",
+        "### Suggested next step",
+        "Run `waypoint_test` after applying the fix to confirm no regressions.",
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+}

package/dist/tools/goal.js

@@ -0,0 +1,94 @@
+import { getBaseContext, getArtifact, saveArtifact } from "../context.js";
+export const definition = {
+    name: "waypoint_goal",
+    description: "Define or refine the project goal. Analyzes existing code and business logic if present.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            workspacePath: {
+                type: "string",
+                description: "Absolute path to the workspace root.",
+            },
+            goal: {
+                type: "string",
+                description: "The goal to define or refine. Omit to review an existing goal.md.",
+            },
+        },
+        required: ["workspacePath"],
+    },
+};
+export async function run(args) {
+    const { workspacePath, goal } = args;
+    const ctx = await getBaseContext(workspacePath);
+    const existing = await getArtifact(workspacePath, "goal.md");
+    const goalStatement = goal ?? existing?.match(/^# Goal\n+(.+)/m)?.[1] ?? null;
+    const workspaceSummary = [
+        `**Path:** ${workspacePath}`,
+        ctx.packageJson
+            ? `**Package:** ${(() => {
+                try {
+                    const p = JSON.parse(ctx.packageJson);
+                    return `${p.name ?? "unnamed"} v${p.version ?? "?"}`;
+                }
+                catch {
+                    return "present (unparseable)";
+                }
+            })()}`
+            : "**Package:** none detected",
+        `**Files (2 levels):**\n\`\`\`\n${ctx.fileTree}\n\`\`\``,
+        Object.keys(ctx.waypointArtifacts).length > 0
+            ? `**Existing .waypoint artifacts:** ${Object.keys(ctx.waypointArtifacts).join(", ")}`
+            : "**Existing .waypoint artifacts:** none",
+    ].join("\n");
+    if (!goalStatement) {
+        return [
+            "## waypoint_goal — No goal defined yet",
+            "",
+            "### Workspace snapshot",
+            workspaceSummary,
+            "",
+            "### Next step",
+            "Call `waypoint_goal` again with a `goal` parameter describing what you want to achieve.",
+            "Example: _\"Add user authentication with email/password and OAuth\"_",
+            "",
+            "A clear goal should answer:",
+            "- What capability or outcome are we delivering?",
+            "- Who benefits and how?",
+            "- What does done look like?",
+        ].join("\n");
+    }
+    const artifact = [
+        "# Goal",
+        "",
+        goalStatement,
+        "",
+        "## Success criteria",
+        "<!-- Define 2-4 measurable outcomes that confirm this goal is met -->",
+        "- [ ] ",
+        "",
+        "## Out of scope",
+        "<!-- Explicitly list what this goal does NOT cover -->",
+        "- ",
+        "",
+        "## Workspace observations",
+        workspaceSummary,
+        "",
+        `_Generated by waypoint_goal — ${new Date().toISOString()}_`,
+    ].join("\n");
+    await saveArtifact(workspacePath, "goal.md", artifact);
+    return [
+        "## waypoint_goal — Goal captured",
+        "",
+        `**Goal:** ${goalStatement}`,
+        "",
+        "### Workspace snapshot",
+        workspaceSummary,
+        "",
+        "### Artifact saved",
+        "`goal.md` written to `.waypoint/goal.md`.",
+        "Fill in **Success criteria** and **Out of scope** before moving to `waypoint_research`.",
+        "",
+        "### Suggested next step",
+        "Run `waypoint_research` to surface best practices and open questions for this goal.",
+    ].join("\n");
+}

package/dist/tools/improve.js

@@ -0,0 +1,99 @@
+import { getBaseContext, getArtifact, saveArtifact } from "../context.js";
+export const definition = {
+    name: "waypoint_improve",
+    description: "Propose refinements. Distinguish must-haves from optional enhancements.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            workspacePath: {
+                type: "string",
+                description: "Absolute path to the workspace root.",
+            },
+            area: {
+                type: "string",
+                description: "Specific area to improve (optional). Omit to generate improvements across all areas.",
+            },
+        },
+        required: ["workspacePath"],
+    },
+};
+export async function run(args) {
+    const { workspacePath, area } = args;
+    const ctx = await getBaseContext(workspacePath);
+    const goalArtifact = await getArtifact(workspacePath, "goal.md");
+    const measureArtifact = await getArtifact(workspacePath, "measure.md");
+    const buildArtifact = await getArtifact(workspacePath, "build.md");
+    if (!goalArtifact) {
+        return [
+            "## waypoint_improve — No goal found",
+            "",
+            "Run `waypoint_goal` first — improvements require a defined goal to improve toward.",
+        ].join("\n");
+    }
+    const goalLine = goalArtifact.match(/^# Goal\n+(.+)/m)?.[1] ?? "(goal not parsed)";
+    const hasMeasure = !!measureArtifact;
+    const artifact = [
+        "# Improve",
+        "",
+        `**Goal:** ${goalLine}`,
+        area ? `**Area:** ${area}` : "",
+        !hasMeasure
+            ? "\n> ⚠️ No measure.md found — running `waypoint_measure` first gives better improvement signals."
+            : "",
+        "",
+        "## Must-have improvements",
+        "<!-- Fixes that affect correctness, reliability, or core usability — do these now -->",
+        "- [ ] ",
+        "",
+        "## Should-have improvements",
+        "<!-- Meaningful quality improvements — do before next major release -->",
+        "- [ ] ",
+        "",
+        "## Nice-to-have enhancements",
+        "<!-- Optional upgrades — only if time and priority allow -->",
+        "- [ ] ",
+        "",
+        "## Out of scope",
+        "<!-- Improvements explicitly not being pursued and why -->",
+        "- ",
+        "",
+        "## Improvement prompts for AI coding tools",
+        "",
+        "### Refactor prompt",
+        "```",
+        `Improve the following area without changing behavior: ${area ?? goalLine}`,
+        "",
+        "Constraints:",
+        "- Do not change externally observable behavior",
+        "- Keep changes focused on the area being improved",
+        "- Prefer simplicity over cleverness",
+        "```",
+        "",
+        `_Generated by waypoint_improve — ${new Date().toISOString()}_`,
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+    await saveArtifact(workspacePath, "improve.md", artifact);
+    return [
+        "## waypoint_improve — Improvement plan generated",
+        "",
+        `**Goal:** ${goalLine}`,
+        area ? `**Area:** ${area}` : "",
+        !hasMeasure
+            ? "\n> No measure.md found — run `waypoint_measure` for data-driven improvements."
+            : "",
+        "",
+        "### Three tiers",
+        "- **Must-have** — correctness and reliability issues; do these now",
+        "- **Should-have** — meaningful quality improvements; do before next release",
+        "- **Nice-to-have** — optional enhancements; defer unless time allows",
+        "",
+        "### Artifact saved",
+        "`improve.md` written to `.waypoint/improve.md`.",
+        "",
+        "### Suggested next step",
+        "Run `waypoint_document` to document the improved state, or `waypoint_review` for a final quality check.",
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+}

package/dist/tools/measure.js

@@ -0,0 +1,101 @@
+import { getBaseContext, getArtifact, saveArtifact } from "../context.js";
+export const definition = {
+    name: "waypoint_measure",
+    description: "Evaluate overall project success against defined goals.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            workspacePath: {
+                type: "string",
+                description: "Absolute path to the workspace root.",
+            },
+        },
+        required: ["workspacePath"],
+    },
+};
+export async function run(args) {
+    const { workspacePath } = args;
+    const ctx = await getBaseContext(workspacePath);
+    const goalArtifact = await getArtifact(workspacePath, "goal.md");
+    const buildArtifact = await getArtifact(workspacePath, "build.md");
+    const testArtifact = await getArtifact(workspacePath, "test.md");
+    if (!goalArtifact) {
+        return [
+            "## waypoint_measure — No goal found",
+            "",
+            "Run `waypoint_goal` first — measurement requires a defined goal to evaluate against.",
+        ].join("\n");
+    }
+    const goalLine = goalArtifact.match(/^# Goal\n+(.+)/m)?.[1] ?? "(goal not parsed)";
+    const successCriteriaBlock = goalArtifact.match(/## Success criteria\n([\s\S]*?)(?=\n##|$)/)?.[1]?.trim() ?? "";
+    const criteriaLines = successCriteriaBlock
+        .split("\n")
+        .filter((l) => l.trim().startsWith("- ["))
+        .map((l) => l.trim());
+    const criteriaRows = criteriaLines.length > 0
+        ? criteriaLines.map((c) => `| ${c} | | |`)
+        : ["| - (no criteria defined in goal.md) | | |"];
+    const missing = [
+        !buildArtifact && "build.md",
+        !testArtifact && "test.md",
+    ].filter(Boolean);
+    const artifact = [
+        "# Measure",
+        "",
+        `**Goal:** ${goalLine}`,
+        missing.length > 0
+            ? `\n> ⚠️ Missing: ${missing.join(", ")} — measurement may be incomplete.`
+            : "",
+        "",
+        "## Success criteria scorecard",
+        "| Criterion | Status | Evidence |",
+        "|-----------|--------|----------|",
+        ...criteriaRows,
+        "",
+        "## Overall verdict",
+        "<!-- One of: ✅ Goal met | ⚠️ Partially met | ❌ Not met -->",
+        "**Verdict:** ",
+        "**Summary:** ",
+        "",
+        "## What worked well",
+        "- ",
+        "",
+        "## What fell short",
+        "- ",
+        "",
+        "## Quantitative signals",
+        "<!-- Add any measurable data: test pass rate, latency, bundle size, etc. -->",
+        "| Metric | Target | Actual | Pass? |",
+        "|--------|--------|--------|-------|",
+        "| | | | |",
+        "",
+        `_Generated by waypoint_measure — ${new Date().toISOString()}_`,
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+    await saveArtifact(workspacePath, "measure.md", artifact);
+    return [
+        "## waypoint_measure — Measurement framework generated",
+        "",
+        `**Goal:** ${goalLine}`,
+        missing.length > 0 ? `\n> Missing: ${missing.join(", ")} — add these for fuller measurement.` : "",
+        "",
+        criteriaLines.length > 0
+            ? `**${criteriaLines.length} success criteria** pulled from goal.md into scorecard.`
+            : "**No success criteria found in goal.md.** Fill in the scorecard manually.",
+        "",
+        "### How to use measure.md",
+        "1. Score each criterion: ✅ met / ⚠️ partial / ❌ not met",
+        "2. Add evidence for each",
+        "3. Record quantitative signals where available",
+        "4. Write the overall verdict",
+        "",
+        "### Artifact saved",
+        "`measure.md` written to `.waypoint/measure.md`.",
+        "",
+        "### Suggested next step",
+        "Run `waypoint_improve` to identify refinements based on what fell short.",
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+}

package/dist/tools/plan.js

@@ -0,0 +1,107 @@
+import { getBaseContext, getArtifact, saveArtifact } from "../context.js";
+export const definition = {
+    name: "waypoint_plan",
+    description: "Create a structured plan for new features or significant changes only.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            workspacePath: {
+                type: "string",
+                description: "Absolute path to the workspace root.",
+            },
+            scope: {
+                type: "string",
+                description: "Specific scope or milestone to plan (optional). Omit to plan the full goal.",
+            },
+        },
+        required: ["workspacePath"],
+    },
+};
+export async function run(args) {
+    const { workspacePath, scope } = args;
+    const ctx = await getBaseContext(workspacePath);
+    const goalArtifact = await getArtifact(workspacePath, "goal.md");
+    const optionsArtifact = await getArtifact(workspacePath, "compare.md");
+    const researchArtifact = await getArtifact(workspacePath, "research.md");
+    if (!goalArtifact) {
+        return [
+            "## waypoint_plan — No goal found",
+            "",
+            "Run `waypoint_goal` before planning.",
+        ].join("\n");
+    }
+    const goalLine = goalArtifact.match(/^# Goal\n+(.+)/m)?.[1] ?? "(goal not parsed)";
+    const missing = [
+        !researchArtifact && "research.md",
+        !optionsArtifact && "compare.md",
+    ].filter(Boolean);
+    const artifact = [
+        "# Plan",
+        "",
+        `**Goal:** ${goalLine}`,
+        scope ? `**Scope:** ${scope}` : "",
+        missing.length > 0
+            ? `\n> ⚠️ Missing prior artifacts: ${missing.join(", ")}. Plan may be incomplete.`
+            : "",
+        "",
+        "## Milestones",
+        "<!-- Break the work into 2–5 ordered milestones -->",
+        "",
+        "### Milestone 1 — Foundation",
+        "**Deliverable:** ",
+        "**Done when:** ",
+        "**Steps:**",
+        "- [ ] ",
+        "",
+        "### Milestone 2 — Core feature",
+        "**Deliverable:** ",
+        "**Done when:** ",
+        "**Steps:**",
+        "- [ ] ",
+        "",
+        "### Milestone 3 — Polish & ship",
+        "**Deliverable:** ",
+        "**Done when:** ",
+        "**Steps:**",
+        "- [ ] ",
+        "",
+        "## Dependencies",
+        "<!-- External dependencies or blockers between milestones -->",
+        "- ",
+        "",
+        "## Out of scope for this plan",
+        "- ",
+        "",
+        "## Risk register",
+        "| Risk | Likelihood | Impact | Mitigation |",
+        "|------|-----------|--------|------------|",
+        "| | | | |",
+        "",
+        `_Generated by waypoint_plan — ${new Date().toISOString()}_`,
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+    await saveArtifact(workspacePath, "plan.md", artifact);
+    return [
+        "## waypoint_plan — Plan generated",
+        "",
+        `**Goal:** ${goalLine}`,
+        scope ? `**Scope:** ${scope}` : "",
+        missing.length > 0
+            ? `\n> Missing: ${missing.join(", ")} — plan may be incomplete.`
+            : "",
+        "",
+        "### Structure",
+        "- **3 milestones** scaffolded — fill in deliverables, done-when criteria, and steps",
+        "- **Risk register** — add any known risks before building",
+        "- **Dependencies** — note anything that must be resolved first",
+        "",
+        "### Artifact saved",
+        "`plan.md` written to `.waypoint/plan.md`.",
+        "",
+        "### Suggested next step",
+        "Run `waypoint_build` to scaffold implementation from this plan.",
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+}

package/dist/tools/research.js

@@ -0,0 +1,104 @@
+import { getBaseContext, getArtifact, saveArtifact } from "../context.js";
+export const definition = {
+    name: "waypoint_research",
+    description: "Gather best practices, surface the right questions, explore the solution space.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            workspacePath: {
+                type: "string",
+                description: "Absolute path to the workspace root.",
+            },
+            topic: {
+                type: "string",
+                description: "Specific research focus (optional). Omit to research the full goal.",
+            },
+        },
+        required: ["workspacePath"],
+    },
+};
+export async function run(args) {
+    const { workspacePath, topic } = args;
+    const ctx = await getBaseContext(workspacePath);
+    const goalArtifact = await getArtifact(workspacePath, "goal.md");
+    if (!goalArtifact) {
+        return [
+            "## waypoint_research — No goal found",
+            "",
+            "Run `waypoint_goal` first to define the project goal before researching.",
+        ].join("\n");
+    }
+    const goalLine = goalArtifact.match(/^# Goal\n+(.+)/m)?.[1] ?? "(goal not parsed)";
+    const focus = topic ?? goalLine;
+    const artifact = [
+        "# Research",
+        "",
+        `**Goal:** ${goalLine}`,
+        topic ? `**Focus:** ${topic}` : "",
+        "",
+        "## Key questions to answer",
+        "<!-- What must be understood before committing to a design? -->",
+        "- What existing solutions or libraries handle this well?",
+        "- What constraints (performance, security, compatibility) apply?",
+        "- What has failed in similar past attempts?",
+        "- What unknowns could invalidate the plan?",
+        "",
+        "## Areas to investigate",
+        "",
+        "### Prior art & libraries",
+        "- [ ] Survey existing libraries and tools relevant to the goal",
+        "- [ ] Review documentation and known limitations",
+        "",
+        "### Architecture & patterns",
+        "- [ ] Identify applicable design patterns",
+        "- [ ] Assess integration points with existing code",
+        "",
+        "### Risks & constraints",
+        "- [ ] List technical risks",
+        "- [ ] Note hard constraints (runtime, platform, team)",
+        "",
+        "### Open decisions",
+        "<!-- Questions that will need to be resolved in waypoint_compare -->",
+        "- [ ] ",
+        "",
+        "## Workspace observations",
+        `**Path:** ${workspacePath}`,
+        ctx.packageJson
+            ? (() => {
+                try {
+                    const p = JSON.parse(ctx.packageJson);
+                    return `**Package:** ${p.name ?? "unnamed"} v${p.version ?? "?"}`;
+                }
+                catch {
+                    return "**Package:** present (unparseable)";
+                }
+            })()
+            : "**Package:** none detected",
+        "",
+        `_Generated by waypoint_research — ${new Date().toISOString()}_`,
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+    await saveArtifact(workspacePath, "research.md", artifact);
+    return [
+        "## waypoint_research — Research brief generated",
+        "",
+        `**Goal:** ${goalLine}`,
+        topic ? `**Focus:** ${topic}` : "",
+        "",
+        "### What to investigate",
+        "1. **Prior art & libraries** — survey what exists, note limitations",
+        "2. **Architecture & patterns** — find applicable patterns, assess fit",
+        "3. **Risks & constraints** — surface blockers early",
+        "4. **Open decisions** — list what must be resolved before planning",
+        "",
+        "### Artifact saved",
+        "`research.md` written to `.waypoint/research.md`.",
+        "Fill in findings before moving forward.",
+        "",
+        "### Suggested next step",
+        "Run `waypoint_compare` to turn research findings into concrete decision tradeoffs.",
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+}