@waycraft/waypoint-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# Waypoint
+
+A structured development protocol as an MCP server. 14 tools that guide any project from goal to ship — for engineers and non-technical stakeholders alike.
+
+Each tool reads your workspace automatically. No setup or briefing required. Tools write structured artifacts to a `.waypoint/` folder, building a shared record of decisions, designs, plans, and reviews as you work.
+
+---
+
+## Install
+
+```sh
+npx @waycraft/waypoint-mcp
+```
+
+Or add permanently via Claude Code:
+
+```sh
+claude mcp add waypoint npx @waycraft/waypoint-mcp
+```
+
+---
+
+## Connect manually
+
+Add to `~/.claude/mcp.json` (global) or `.claude/mcp.json` (project-level):
+
+```json
+{
+  "mcpServers": {
+    "waypoint": {
+      "command": "npx",
+      "args": ["@waycraft/waypoint-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Code after editing `mcp.json`.
+
+---
+
+## The 14 tools
+
+| Tool | What it does |
+|------|-------------|
+| `waypoint_goal` | Define what you're building and why |
+| `waypoint_research` | Surface what you need to know first |
+| `waypoint_compare` | Weigh your options and tradeoffs |
+| `waypoint_plan` | Map out how and when you'll build it |
+| `waypoint_design` | Set the structural contract before building |
+| `waypoint_build` | Scaffold the implementation |
+| `waypoint_test` | Verify it works |
+| `waypoint_fix` | Fix what's broken |
+| `waypoint_debug` | Find out why it's broken |
+| `waypoint_audit` | Check design health — tiered Must Fix / Should Fix findings |
+| `waypoint_measure` | Evaluate whether you hit the goal |
+| `waypoint_improve` | Identify what to make better |
+| `waypoint_document` | Write it up for others |
+| `waypoint_review` | Final check before you ship |
+
+Every tool accepts `workspacePath` (required) — the absolute path to the project you're working on.
+
+---
+
+## The journey
+
+```
+waypoint_goal → waypoint_research → waypoint_compare → waypoint_plan → waypoint_design
+             → waypoint_build → waypoint_test → waypoint_fix → waypoint_debug → waypoint_audit
+             → waypoint_measure → waypoint_improve → waypoint_document → waypoint_review
+```
+
+Tools are independent — call any one at any time. The order above is the natural progression, not a requirement.
+
+---
+
+## How artifacts work
+
+Each tool writes a markdown file to `.waypoint/` in your workspace:
+
+```
+your-project/
+└── .waypoint/
+    ├── goal.md
+    ├── research.md
+    ├── compare.md
+    ├── plan.md
+    ├── design.md
+    ├── build.md
+    ├── test.md
+    ├── fix.md
+    ├── debug.md
+    ├── audit.md
+    ├── measure.md
+    ├── improve.md
+    ├── docs.md
+    └── review.md
+```
+
+Artifacts are plain markdown — edit them directly. Later tools read earlier ones to stay in context. Commit `.waypoint/` to version control to preserve the record.
+
+---
+
+## Running tests
+
+```sh
+npm test
+```
+
+Each tool has its own test file in `tests/`. Tests spin up the MCP server over stdio, send real JSON-RPC calls, and assert on output and artifacts written to disk.

package/dist/context.js

@@ -0,0 +1,79 @@
+import { readFile, writeFile, readdir, mkdir, stat } from "fs/promises";
+import { join, relative } from "path";
+const SKIP_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", ".next", ".nuxt",
+    "coverage", ".cache", ".turbo", "out",
+]);
+async function listTree(dir, depth, root) {
+    if (depth === 0)
+        return [];
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const lines = [];
+    for (const entry of entries.sort()) {
+        if (entry.startsWith(".") && entry !== ".waypoint")
+            continue;
+        if (SKIP_DIRS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        const rel = relative(root, full);
+        let isDir = false;
+        try {
+            isDir = (await stat(full)).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        lines.push(isDir ? `${rel}/` : rel);
+        if (isDir) {
+            lines.push(...await listTree(full, depth - 1, root));
+        }
+    }
+    return lines;
+}
+export async function getBaseContext(workspacePath) {
+    const treeLines = await listTree(workspacePath, 2, workspacePath);
+    const fileTree = treeLines.length > 0 ? treeLines.join("\n") : "(empty workspace)";
+    let packageJson = null;
+    try {
+        packageJson = await readFile(join(workspacePath, "package.json"), "utf8");
+    }
+    catch {
+        // not a Node project — fine
+    }
+    const waypointArtifacts = {};
+    const waypointDir = join(workspacePath, ".waypoint");
+    try {
+        const files = await readdir(waypointDir);
+        for (const file of files.sort()) {
+            try {
+                waypointArtifacts[file] = await readFile(join(waypointDir, file), "utf8");
+            }
+            catch {
+                // skip unreadable files
+            }
+        }
+    }
+    catch {
+        // no .waypoint directory yet — fine
+    }
+    return { workspacePath, fileTree, packageJson, waypointArtifacts };
+}
+export async function getArtifact(workspacePath, filename) {
+    try {
+        return await readFile(join(workspacePath, ".waypoint", filename), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveArtifact(workspacePath, filename, content) {
+    const waypointDir = join(workspacePath, ".waypoint");
+    await mkdir(waypointDir, { recursive: true });
+    await writeFile(join(waypointDir, filename), content, "utf8");
+}

package/dist/index.js

@@ -0,0 +1,46 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import * as goal from "./tools/goal.js";
+import * as research from "./tools/research.js";
+import * as compare from "./tools/compare.js";
+import * as plan from "./tools/plan.js";
+import * as design from "./tools/design.js";
+import * as build from "./tools/build.js";
+import * as test from "./tools/test.js";
+import * as fix from "./tools/fix.js";
+import * as debug from "./tools/debug.js";
+import * as audit from "./tools/audit.js";
+import * as measure from "./tools/measure.js";
+import * as improve from "./tools/improve.js";
+import * as document from "./tools/document.js";
+import * as review from "./tools/review.js";
+const tools = [goal, research, compare, plan, design, build, test, fix, debug, audit, measure, improve, document, review];
+const server = new Server({ name: "waypoint-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => t.definition),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = tools.find((t) => t.definition.name === name);
+    if (!tool) {
+        return {
+            content: [{ type: "text", text: `Unknown tool: ${name}` }],
+            isError: true,
+        };
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const text = await tool.run(args);
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Tool error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/audit.js

@@ -0,0 +1,311 @@
+import { getBaseContext, getArtifact, saveArtifact } from "../context.js";
+export const definition = {
+    name: "waypoint_audit",
+    description: "Diagnostic design health check on existing code. Infers project tier, confirms with one question, then produces tiered findings: Must Fix, Should Fix, Consider Later. Runs after Build or Fix, or standalone on any existing codebase.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            workspacePath: {
+                type: "string",
+                description: "Absolute path to the workspace root.",
+            },
+            tier: {
+                type: "string",
+                enum: ["prototype", "product", "platform"],
+                description: "Explicitly set the project tier (optional). Omit to let waypoint_audit infer it and ask for confirmation.",
+            },
+            focus: {
+                type: "string",
+                description: "Specific file, folder, or concern to audit (optional). E.g. 'auth/', 'routes/user.js', 'error handling'. Omit to audit the full codebase.",
+            },
+        },
+        required: ["workspacePath"],
+    },
+};
+// ─── Tier inference ───────────────────────────────────────────────────────────
+function inferTier(ctx) {
+    let score = 0;
+    const fileTree = ctx.fileTree ?? "";
+    const pkg = (() => {
+        try {
+            return JSON.parse(ctx.packageJson ?? "{}");
+        }
+        catch {
+            return {};
+        }
+    })();
+    const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+    const allText = [fileTree, ctx.packageJson ?? ""].join("\n").toLowerCase();
+    const fileCount = (fileTree.match(/\n/g) ?? []).length;
+    if (fileCount > 40)
+        score += 2;
+    else if (fileCount > 15)
+        score += 1;
+    if (allText.includes("dockerfile") || allText.includes("docker-compose"))
+        score += 2;
+    if (allText.includes(".github/workflows") || allText.includes("ci.yml"))
+        score += 1;
+    if (allText.includes(".env.example") || allText.includes("config/"))
+        score += 1;
+    if (deps.some(d => ["prisma", "typeorm", "sequelize", "drizzle", "mongoose"].includes(d)))
+        score += 2;
+    if (deps.some(d => ["passport", "jsonwebtoken", "next-auth", "clerk"].includes(d)))
+        score += 1;
+    if (deps.some(d => ["jest", "vitest", "mocha", "playwright", "cypress"].includes(d)))
+        score += 1;
+    if (deps.some(d => ["@anthropic-ai/sdk", "openai", "langchain"].includes(d)))
+        score += 1;
+    if (allText.includes("console.log") && fileCount < 10)
+        score -= 1;
+    if (!ctx.packageJson)
+        score -= 1;
+    if (score >= 6)
+        return { tier: "platform", confidence: "high" };
+    if (score >= 3)
+        return { tier: "product", confidence: score >= 4 ? "high" : "medium" };
+    return { tier: "prototype", confidence: score <= 1 ? "high" : "medium" };
+}
+const FINDINGS = [
+    {
+        id: "secrets",
+        label: "Hardcoded secrets or credentials in code",
+        detail: "Any API key, password, or token literal in source code is a credential leak risk. Move to environment variables and add to .env.example.",
+        severity: { prototype: "must", product: "must", platform: "must" },
+    },
+    {
+        id: "no-error-handling",
+        label: "Unhandled promise rejections or missing try/catch on I/O",
+        detail: "Silent failures corrupt state and are hard to debug in production. Every async I/O path needs explicit error handling.",
+        severity: { prototype: "must", product: "must", platform: "must" },
+    },
+    {
+        id: "god-file",
+        label: "God file or module (single file doing too much)",
+        detail: "Files over ~200 lines that mix concerns (routing, logic, data access) become hard to test and change. Split by responsibility.",
+        severity: { prototype: "should", product: "must", platform: "must" },
+    },
+    {
+        id: "auth-inline",
+        label: "Auth logic inside route handlers",
+        detail: "Auth mixed into handlers can't be tested in isolation and is easy to omit on new routes. Extract to middleware.",
+        severity: { prototype: "should", product: "must", platform: "must" },
+    },
+    {
+        id: "no-input-validation",
+        label: "No input validation at system boundaries",
+        detail: "Unvalidated input leads to silent data corruption and security risks. Add schema validation (Zod, joi) before handler logic.",
+        severity: { prototype: "should", product: "must", platform: "must" },
+    },
+    {
+        id: "no-service-layer",
+        label: "Direct DB or external API calls in route handlers",
+        detail: "Bypassing a service layer makes testing require real infrastructure and makes the DB/API harder to swap. Add a services/ or repositories/ layer.",
+        severity: { prototype: "consider", product: "should", platform: "must" },
+    },
+    {
+        id: "scattered-env",
+        label: "Scattered process.env access throughout the codebase",
+        detail: "Direct process.env reads in multiple files make config hard to audit and validate. Centralise in a config module.",
+        severity: { prototype: "consider", product: "should", platform: "must" },
+    },
+    {
+        id: "no-tests",
+        label: "No automated tests",
+        detail: "Without tests, changes regress silently. Add at minimum unit tests for core logic and one integration test per entry point.",
+        severity: { prototype: "consider", product: "should", platform: "must" },
+    },
+    {
+        id: "magic-values",
+        label: "Magic numbers or strings in logic",
+        detail: "Unexplained literals (timeouts, limits, status codes) are hard to understand and change safely. Use named constants.",
+        severity: { prototype: "should", product: "should", platform: "must" },
+    },
+    {
+        id: "no-logging",
+        label: "No structured logging",
+        detail: "console.log is fine early on, but structured logging (with levels and context) is needed before onboarding a team or going to production.",
+        severity: { prototype: "consider", product: "consider", platform: "must" },
+    },
+    {
+        id: "inconsistent-naming",
+        label: "Inconsistent naming conventions",
+        detail: "Mixed camelCase/snake_case, unclear abbreviations, or generic names (data, result, obj) slow down reading. Align on a convention and apply it.",
+        severity: { prototype: "consider", product: "should", platform: "should" },
+    },
+    {
+        id: "inline-prompts",
+        label: "Prompt strings hardcoded inline in business logic",
+        detail: "Inline prompt strings mix concerns and make prompt iteration require code changes. Extract to a dedicated prompts/ module.",
+        severity: { prototype: "consider", product: "should", platform: "must" },
+    },
+    {
+        id: "no-llm-resilience",
+        label: "LLM calls without retry or error handling",
+        detail: "LLM APIs are unreliable — timeouts, rate limits, and transient errors are common. Wrap every call in retry logic with a fallback.",
+        severity: { prototype: "should", product: "must", platform: "must" },
+    },
+    {
+        id: "fat-agent-tools",
+        label: "Agent tool functions with multiple responsibilities",
+        detail: "Tool functions that do too many things degrade model tool-use accuracy and are hard to test. Each tool should do exactly one thing.",
+        severity: { prototype: "consider", product: "should", platform: "must" },
+    },
+    {
+        id: "no-llm-observability",
+        label: "No token usage or cost tracking on LLM calls",
+        detail: "Without observability on LLM usage, costs are invisible and runaway spending is easy to miss. Log token counts at the call site or service layer.",
+        severity: { prototype: "consider", product: "consider", platform: "must" },
+    },
+];
+// ─── Tier label map ───────────────────────────────────────────────────────────
+const TIER_LABELS = {
+    prototype: "Prototype",
+    product: "Product",
+    platform: "Platform",
+};
+// ─── Confirmation note ────────────────────────────────────────────────────────
+function confirmationNote(tier, confidence, explicit) {
+    if (explicit) {
+        return `> **Tier set explicitly: ${TIER_LABELS[tier]}**`;
+    }
+    if (confidence === "high") {
+        return `> **Tier inferred: ${TIER_LABELS[tier]}** (high confidence)\n> If this is wrong, re-run \`waypoint_audit\` with an explicit \`tier\` parameter.`;
+    }
+    const alternates = ["prototype", "product", "platform"].filter(t => t !== tier);
+    return [
+        `> **Tier inferred: ${TIER_LABELS[tier]}** (medium confidence — mixed signals)`,
+        `> Re-run with \`tier: "${alternates[0]}"\` or \`"${alternates[1]}"\` if this doesn't match your intent.`,
+    ].join("\n");
+}
+// ─── Run ──────────────────────────────────────────────────────────────────────
+export async function run(args) {
+    const { workspacePath, tier: explicitTier, focus } = args;
+    const ctx = await getBaseContext(workspacePath);
+    const buildArtifact = await getArtifact(workspacePath, "build.md");
+    const goalArtifact = await getArtifact(workspacePath, "goal.md");
+    const designArtifact = await getArtifact(workspacePath, "design.md");
+    const fixArtifact = await getArtifact(workspacePath, "fix.md");
+    const goalLine = goalArtifact?.match(/^# Goal\n+(.+)/m)?.[1] ?? "(no goal defined)";
+    let tierKey;
+    let confidence;
+    if (explicitTier) {
+        tierKey = explicitTier;
+        confidence = "explicit";
+    }
+    else {
+        const inferred = inferTier(ctx);
+        tierKey = inferred.tier;
+        confidence = inferred.confidence;
+    }
+    const tierLabel = TIER_LABELS[tierKey];
+    const tierNote = confirmationNote(tierKey, confidence, !!explicitTier);
+    const contextNotes = [
+        !buildArtifact && !goalArtifact && "> ℹ️ No EDP context found — running as standalone audit on existing codebase.",
+        !buildArtifact && goalArtifact && "> ⚠️ No build.md found — audit has no build baseline.",
+        designArtifact && "> ✅ design.md found — checking compliance with design contract.",
+        fixArtifact && "> ℹ️ fix.md present — checking that recent fixes haven't introduced structural drift.",
+    ].filter(Boolean);
+    const must = FINDINGS.filter(f => f.severity[tierKey] === "must");
+    const should = FINDINGS.filter(f => f.severity[tierKey] === "should");
+    const consider = FINDINGS.filter(f => f.severity[tierKey] === "consider");
+    const pkg = (() => {
+        try {
+            return JSON.parse(ctx.packageJson ?? "{}");
+        }
+        catch {
+            return {};
+        }
+    })();
+    const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+    const isAiNative = deps.some(d => ["@anthropic-ai/sdk", "openai", "langchain", "@langchain"].includes(d));
+    const aiFindings = ["inline-prompts", "no-llm-resilience", "fat-agent-tools", "no-llm-observability"];
+    function renderFindings(findings) {
+        if (findings.length === 0)
+            return ["_None at this tier._"];
+        return findings.flatMap((f, i) => {
+            const isAi = aiFindings.includes(f.id);
+            const tag = isAiNative && isAi ? " _(AI-native)_" : "";
+            const focusNote = focus ? ` _(check in: ${focus})_` : "";
+            return [
+                `### ${i + 1}. ${f.label}${tag}`,
+                `${f.detail}${focusNote}`,
+                "- [ ] Investigated",
+                "- [ ] Action taken or explicitly deferred",
+                "",
+            ];
+        });
+    }
+    const artifact = [
+        "# Audit",
+        "",
+        `**Goal:** ${goalLine}`,
+        focus ? `**Focus:** ${focus}` : "",
+        `**Tier:** ${tierLabel}`,
+        ...contextNotes,
+        "",
+        tierNote,
+        "",
+        "## Must Fix",
+        "<!-- Address these before shipping or sharing this code -->",
+        "",
+        ...renderFindings(must),
+        "## Should Fix",
+        "<!-- Address before next release or when touching this area -->",
+        "",
+        ...renderFindings(should),
+        "## Consider Later",
+        "<!-- Worth doing at scale — not urgent at current tier -->",
+        "",
+        ...renderFindings(consider),
+        "## Design contract compliance",
+        designArtifact
+            ? "<!-- Check findings against the contract in design.md -->"
+            : "<!-- No design.md found — run `waypoint_design` to establish a contract, then re-audit -->",
+        "- [ ] All Must Fix items from the design contract are addressed",
+        "- [ ] Structure matches design.md recommendations",
+        "",
+        "## Audit summary",
+        `| Severity | Count |`,
+        `|----------|-------|`,
+        `| Must Fix | ${must.length} |`,
+        `| Should Fix | ${should.length} |`,
+        `| Consider Later | ${consider.length} |`,
+        "",
+        "**Overall verdict:**",
+        "<!-- ✅ Clean | ⚠️ Needs attention | ❌ Significant issues -->",
+        "",
+        `_Generated by waypoint_audit (${tierLabel}) — ${new Date().toISOString()}_`,
+    ]
+        .filter(l => l !== undefined)
+        .join("\n");
+    await saveArtifact(workspacePath, "audit.md", artifact);
+    const hasMust = must.length > 0;
+    const hasShould = should.length > 0;
+    const nextStep = hasMust
+        ? "Run `waypoint_fix` for Must Fix items — minimal targeted patches. Then re-run `waypoint_audit` to confirm."
+        : hasShould
+            ? "No Must Fix items. Run `waypoint_improve` to work through Should Fix items as structured refactors."
+            : "No Must Fix or Should Fix items. Run `waypoint_review` for a final pre-ship quality check.";
+    return [
+        "## waypoint_audit — Audit complete",
+        "",
+        `**Tier:** ${tierLabel}`,
+        `**Goal:** ${goalLine}`,
+        focus ? `**Focus:** ${focus}` : "",
+        isAiNative ? "**AI-native patterns:** checked" : "",
+        "",
+        "### Findings summary",
+        `- **Must Fix:** ${must.length} — address before shipping`,
+        `- **Should Fix:** ${should.length} — address before next release`,
+        `- **Consider Later:** ${consider.length} — low urgency at current tier`,
+        "",
+        "### Artifact saved",
+        "`audit.md` written to `.waypoint/audit.md`.",
+        "Work through each checklist item — check off as you investigate and act.",
+        "",
+        "### Suggested next step",
+        nextStep,
+    ]
+        .filter(l => l !== undefined)
+        .join("\n");
+}

package/dist/tools/build.js

@@ -0,0 +1,112 @@
+import { getBaseContext, getArtifact, saveArtifact } from "../context.js";
+export const definition = {
+    name: "waypoint_build",
+    description: "Scaffold and implement. Generate prompts and guidance for AI coding tools.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            workspacePath: {
+                type: "string",
+                description: "Absolute path to the workspace root.",
+            },
+            task: {
+                type: "string",
+                description: "Specific build task or milestone to implement (optional). Omit to build from the full plan.",
+            },
+        },
+        required: ["workspacePath"],
+    },
+};
+export async function run(args) {
+    const { workspacePath, task } = args;
+    const ctx = await getBaseContext(workspacePath);
+    const planArtifact = await getArtifact(workspacePath, "plan.md");
+    const goalArtifact = await getArtifact(workspacePath, "goal.md");
+    if (!planArtifact && !goalArtifact) {
+        return [
+            "## waypoint_build — No plan or goal found",
+            "",
+            "Run `waypoint_goal` → `waypoint_plan` before building.",
+        ].join("\n");
+    }
+    const goalLine = goalArtifact?.match(/^# Goal\n+(.+)/m)?.[1] ?? "(goal not parsed)";
+    const hasPlan = !!planArtifact;
+    const pkgName = (() => {
+        try {
+            return JSON.parse(ctx.packageJson ?? "{}").name ?? "this project";
+        }
+        catch {
+            return "this project";
+        }
+    })();
+    const artifact = [
+        "# Build",
+        "",
+        `**Goal:** ${goalLine}`,
+        task ? `**Task:** ${task}` : "",
+        !hasPlan ? "\n> ⚠️ No plan.md found — consider running `waypoint_plan` first." : "",
+        "",
+        "## Implementation checklist",
+        "<!-- Track each implementation unit -->",
+        "- [ ] Set up project structure / scaffold",
+        "- [ ] Implement core logic",
+        "- [ ] Wire up integrations",
+        "- [ ] Handle edge cases and errors",
+        "- [ ] Self-review before handoff to waypoint_test",
+        "",
+        "## AI coding prompts",
+        "<!-- Paste these into your AI coding tool (Claude Code, Cursor, etc.) -->",
+        "",
+        "### Scaffold prompt",
+        "```",
+        `Scaffold the implementation for: ${task ?? goalLine}`,
+        `Project: ${pkgName}`,
+        "Requirements:",
+        "- [fill from plan milestones]",
+        "- Keep changes minimal and focused",
+        "- No speculative features",
+        "```",
+        "",
+        "### Implementation prompt",
+        "```",
+        `Implement: ${task ?? goalLine}`,
+        "Constraints:",
+        "- Match existing code style",
+        "- No new dependencies unless necessary",
+        "- Write no comments unless the why is non-obvious",
+        "```",
+        "",
+        "## Implementation notes",
+        "<!-- Record decisions made during build, gotchas, deviations from plan -->",
+        "- ",
+        "",
+        "## Files changed",
+        "<!-- List key files created or modified -->",
+        "- ",
+        "",
+        `_Generated by waypoint_build — ${new Date().toISOString()}_`,
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+    await saveArtifact(workspacePath, "build.md", artifact);
+    return [
+        "## waypoint_build — Build guide generated",
+        "",
+        `**Goal:** ${goalLine}`,
+        task ? `**Task:** ${task}` : "",
+        !hasPlan ? "\n> No plan.md found — output may be generic. Run `waypoint_plan` first." : "",
+        "",
+        "### AI coding prompts included",
+        "- **Scaffold prompt** — use to create initial structure",
+        "- **Implementation prompt** — use for each milestone or task",
+        "",
+        "### Artifact saved",
+        "`build.md` written to `.waypoint/build.md`.",
+        "Fill in the implementation checklist as you work.",
+        "",
+        "### Suggested next step",
+        "Run `waypoint_test` to verify feature-level requirements once implementation is ready.",
+    ]
+        .filter((l) => l !== undefined)
+        .join("\n");
+}