@callumvass/forgeflow-pm 0.1.0 → 0.3.1

package/agents/{issue-creator.md → gh-issue-creator.md}

@@ -1,5 +1,5 @@
 ---
-name: issue-creator
+name: gh-issue-creator
 description: Decomposes a PRD into vertical-slice GitHub issues for autonomous implementation.
 tools: read, write, bash, grep, find
 ---

package/agents/{single-issue-creator.md → gh-single-issue-creator.md}

@@ -1,5 +1,5 @@
 ---
-name: single-issue-creator
+name: gh-single-issue-creator
 description: Turns a rough feature idea into a well-structured GitHub issue by exploring the codebase.
 tools: read, write, bash, grep, find
 ---

package/agents/investigator.md

@@ -0,0 +1,32 @@
+---
+name: investigator
+description: Explores codebases and produces spikes or RFCs using a provided template.
+tools: read, write, edit, bash, grep, find
+---
+
+You are an investigator agent. You explore codebases, research approaches, and produce structured technical documents (spikes, RFCs, or similar) using a provided template.
+
+## Workflow
+
+1. **Read the template** provided in your task. This defines the output structure. Keep every section heading from the template.
+2. **Read the writing-style skill** and follow it exactly.
+3. **Explore the codebase** thoroughly: file structure, key modules, existing patterns, dependencies, tests, config.
+4. **Research externally** if the task involves new libraries, services, or approaches:
+   - Check what dependencies already exist in the project (package.json, go.mod, etc.)
+   - Use `bash` to search the web via `curl` for library comparisons, docs, or alternatives when needed.
+5. **Fill in the template** with your findings. Every section must have substance or be explicitly marked N/A.
+6. **Write the output** as a markdown file in the project root (e.g. `SPIKE-<topic>.md` or `RFC-<topic>.md`, matching the template type).
+
+## Rules
+
+- Follow the template structure exactly. Do not add or remove sections.
+- If the template has placeholder text or instructions in sections, replace them entirely with your findings.
+- Be specific to this codebase. Reference actual file paths, modules, and patterns you found.
+- When comparing approaches, use a table with clear criteria.
+- When recommending libraries, include: name, what it does, monthly downloads or GitHub stars, last release date, and why it fits (or doesn't).
+- If you cannot determine something from the codebase or public information, say so plainly. Do not speculate.
+- Keep the total document under 200 lines unless the template demands more.
+
+## Confluence Pages
+
+If your task includes Confluence page content (template or reference docs), it has already been fetched for you. Use it directly.

package/agents/jira-issue-creator.md

@@ -0,0 +1,43 @@
+---
+name: jira-issue-creator
+description: Decomposes PM documents into Jira issues matching a team's ticket format.
+tools: read, write, bash, grep, find
+---
+
+You are a Jira issue creator agent. You read PM documents and decompose them into well-structured Jira issues.
+
+## Workflow
+
+1. **Read the writing-style skill** and follow it exactly.
+2. **Read the example ticket** provided in your task. This defines the structure, tone, and level of detail your issues must match. Study it carefully: heading style, section names, how acceptance criteria are written, how technical detail is balanced.
+3. **Read all PM documents** provided. Understand the full scope.
+4. **Explore the codebase** to understand what exists, what needs changing, and where the boundaries are.
+5. **Decompose into vertical-slice issues.** Each issue must be a complete user-observable flow, not a layer (see rules below).
+6. **Create the issues** using `jira issue create` CLI.
+
+## Vertical Slice Rules
+
+Each issue must:
+- Cross all necessary layers (DB, server, client, UI) to deliver one user-observable behaviour.
+- Be independently testable and deployable.
+- Include acceptance criteria describing what the user sees, not what the code does.
+
+Do NOT create:
+- Layer-only issues ("build the API", "add the schema", "create the component").
+- Issues that only make sense when combined with another issue.
+
+## Issue Format
+
+Match the example ticket's format exactly. If the example has sections like Description, Acceptance Criteria, Technical Notes, follow that structure. If it uses a different convention, follow that instead.
+
+## Rules
+
+- Order issues by dependency. If issue B depends on A, say so in B's description.
+- Keep issue count reasonable: 3-8 issues for a typical feature. If you're above 10, you're slicing too thin.
+- Title format: match the example ticket. If it uses imperative ("Add filtering to dashboard"), follow that.
+- Do not invent requirements not present in the PM documents. If something is ambiguous, note it in the issue.
+- Use `jira issue create` to create each issue. Use `--type Story` unless the example ticket indicates otherwise.
+
+## Confluence Pages
+
+If your task includes Confluence page content (PM docs or example tickets), it has already been fetched for you. Use it directly.

package/extensions/index.js

@@ -5,6 +5,61 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// ../shared/dist/confluence.js
+import { spawn } from "child_process";
+function execCmd(cmd) {
+  return new Promise((resolve2) => {
+    const proc = spawn("bash", ["-c", cmd], { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    proc.stdout.on("data", (d) => {
+      out += d.toString();
+    });
+    proc.on("close", () => resolve2(out.trim()));
+    proc.on("error", () => resolve2(""));
+  });
+}
+function extractPageId(url) {
+  const idMatch = url.match(/\/pages\/(\d+)/);
+  if (idMatch)
+    return idMatch[1] ?? null;
+  const paramMatch = url.match(/pageId=(\d+)/);
+  if (paramMatch)
+    return paramMatch[1] ?? null;
+  return null;
+}
+function htmlToPlainText(html) {
+  return html.replace(/<br\s*\/?>/gi, "\n").replace(/<\/p>/gi, "\n\n").replace(/<\/li>/gi, "\n").replace(/<li[^>]*>/gi, "- ").replace(/<\/h[1-6]>/gi, "\n\n").replace(/<h([1-6])[^>]*>/gi, (_m, level) => "#".repeat(parseInt(level, 10)) + " ").replace(/<\/?strong>/gi, "**").replace(/<\/?em>/gi, "*").replace(/<\/?code>/gi, "`").replace(/<ac:structured-macro[^>]*ac:name="code"[^>]*>[\s\S]*?<ac:plain-text-body><!\[CDATA\[([\s\S]*?)\]\]><\/ac:plain-text-body>[\s\S]*?<\/ac:structured-macro>/gi, "\n```\n$1\n```\n").replace(/<[^>]+>/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, " ").replace(/\n{3,}/g, "\n\n").trim();
+}
+async function fetchConfluencePage(pageUrl) {
+  const baseUrl = process.env.CONFLUENCE_URL;
+  const email = process.env.CONFLUENCE_EMAIL;
+  const token = process.env.CONFLUENCE_TOKEN;
+  if (!baseUrl || !email || !token) {
+    return "Missing Confluence env vars. Set CONFLUENCE_URL, CONFLUENCE_EMAIL, and CONFLUENCE_TOKEN.";
+  }
+  const pageId = extractPageId(pageUrl);
+  if (!pageId) {
+    return `Could not extract page ID from URL: ${pageUrl}`;
+  }
+  const auth = Buffer.from(`${email}:${token}`).toString("base64");
+  const apiUrl = `${baseUrl.replace(/\/$/, "")}/wiki/api/v2/pages/${pageId}?body-format=storage`;
+  const raw = await execCmd(`curl -s -H "Authorization: Basic ${auth}" -H "Accept: application/json" "${apiUrl}"`);
+  if (!raw)
+    return `Failed to fetch Confluence page ${pageId}.`;
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return `Could not parse Confluence response for page ${pageId}.`;
+  }
+  const html = data.body?.storage?.value ?? "";
+  return {
+    id: data.id ?? pageId,
+    title: data.title ?? "Untitled",
+    body: htmlToPlainText(html)
+  };
+}
+
 // ../shared/dist/constants.js
 var TOOLS_ALL = ["read", "write", "edit", "bash", "grep", "find"];
 var TOOLS_NO_EDIT = ["read", "write", "bash", "grep", "find"];
@@ -15,7 +70,7 @@ var SIGNALS = {
 };
 
 // ../shared/dist/run-agent.js
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -95,7 +150,7 @@ async function runAgent(agentName, task, options) {
     args.push(`Task: ${task}`);
     const exitCode = await new Promise((resolve2) => {
       const invocation = getPiInvocation(args);
-      const proc = spawn(invocation.command, invocation.args, {
+      const proc = spawn2(invocation.command, invocation.args, {
         cwd: options.cwd,
         shell: false,
         stdio: ["ignore", "pipe", "pipe"]
@@ -358,9 +413,9 @@ Stderr: ${criticResult.stderr.slice(0, 300)}` }],
       if (action === "Accept PRD" || action == null) break;
     }
   }
-  stages.push(emptyStage("issue-creator"));
+  stages.push(emptyStage("gh-issue-creator"));
   await runAgent(
-    "issue-creator",
+    "gh-issue-creator",
     "Decompose PRD.md into vertical-slice GitHub issues. Focus on the ## Next section \u2014 the ## Done section is context only. Read the issue-template skill for the standard format.",
     { ...opts, tools: TOOLS_NO_EDIT }
   );
@@ -372,16 +427,20 @@ Stderr: ${criticResult.stderr.slice(0, 300)}` }],
 
 // src/pipelines/create-issues.ts
 import * as fs4 from "fs";
-async function runCreateIssue(cwd, idea, signal, onUpdate, _ctx) {
+async function runCreateIssue(cwd, idea, signal, onUpdate, ctx) {
+  if (!idea && ctx.hasUI) {
+    const input = await ctx.ui.input("Feature idea?", "");
+    idea = input?.trim() ?? "";
+  }
   if (!idea) {
     return {
       content: [{ type: "text", text: "No feature idea provided." }],
       details: { pipeline: "create-issue", stages: [] }
     };
   }
-  const stages = [emptyStage("single-issue-creator")];
+  const stages = [emptyStage("gh-single-issue-creator")];
   const opts = { agentsDir: AGENTS_DIR, cwd, signal, stages, pipeline: "create-issue", onUpdate };
-  await runAgent("single-issue-creator", idea, { ...opts, tools: TOOLS_NO_EDIT });
+  await runAgent("gh-single-issue-creator", idea, { ...opts, tools: TOOLS_NO_EDIT });
   return {
     content: [{ type: "text", text: "Issue created." }],
     details: { pipeline: "create-issue", stages }
@@ -394,10 +453,10 @@ async function runCreateIssues(cwd, signal, onUpdate, _ctx) {
       details: { pipeline: "create-issues", stages: [] }
     };
   }
-  const stages = [emptyStage("issue-creator")];
+  const stages = [emptyStage("gh-issue-creator")];
   const opts = { agentsDir: AGENTS_DIR, cwd, signal, stages, pipeline: "create-issues", onUpdate };
   await runAgent(
-    "issue-creator",
+    "gh-issue-creator",
     "Decompose PRD.md into vertical-slice GitHub issues. Read the issue-template skill for the standard format.",
     { ...opts, tools: TOOLS_NO_EDIT }
   );
@@ -407,6 +466,128 @@ async function runCreateIssues(cwd, signal, onUpdate, _ctx) {
   };
 }
 
+// src/pipelines/investigate.ts
+async function runInvestigate(cwd, description, templateUrl, signal, onUpdate, ctx) {
+  const interactive = ctx.hasUI;
+  if (!description && interactive) {
+    const input = await ctx.ui.input("What should we investigate?", "");
+    description = input?.trim() ?? "";
+  }
+  if (!description) {
+    return {
+      content: [{ type: "text", text: "No description provided." }],
+      details: { pipeline: "investigate", stages: [] }
+    };
+  }
+  if (!templateUrl && interactive) {
+    const input = await ctx.ui.input("Confluence template URL?", "Skip");
+    if (input != null && input.trim() !== "") {
+      templateUrl = input.trim();
+    }
+  }
+  let templateSection = "";
+  if (templateUrl) {
+    const result = await fetchConfluencePage(templateUrl);
+    if (typeof result === "string") {
+      return {
+        content: [{ type: "text", text: result }],
+        details: { pipeline: "investigate", stages: [] },
+        isError: true
+      };
+    }
+    const page = result;
+    templateSection = `
+
+TEMPLATE (from Confluence page "${page.title}"):
+
+${page.body}`;
+  }
+  const stages = [emptyStage("investigator")];
+  const opts = { agentsDir: AGENTS_DIR, cwd, signal, stages, pipeline: "investigate", onUpdate };
+  const task = `Investigate the following and produce a document using the template provided.
+
+TOPIC: ${description}${templateSection}
+
+${!templateUrl ? "No template was provided. Structure your output as: Problem, Context, Options (with comparison table), Recommendation, Next Steps." : ""}
+
+Read the writing-style skill before writing.`;
+  await runAgent("investigator", task, { ...opts, tools: TOOLS_ALL });
+  return {
+    content: [{ type: "text", text: "Investigation complete." }],
+    details: { pipeline: "investigate", stages }
+  };
+}
+
+// src/pipelines/jira-issues.ts
+async function runJiraIssues(cwd, docUrls, exampleUrl, signal, onUpdate, ctx) {
+  const interactive = ctx.hasUI;
+  if (docUrls.length === 0 && interactive) {
+    const input = await ctx.ui.input("Confluence doc URL(s)?", "Space-separated");
+    if (input != null && input.trim() !== "") {
+      docUrls = input.trim().split(/\s+/).filter(Boolean);
+    }
+  }
+  if (docUrls.length === 0) {
+    return {
+      content: [{ type: "text", text: "No document URLs provided." }],
+      details: { pipeline: "jira-issues", stages: [] }
+    };
+  }
+  if (!exampleUrl && interactive) {
+    const input = await ctx.ui.input("Example ticket URL?", "Skip");
+    if (input != null && input.trim() !== "") {
+      exampleUrl = input.trim();
+    }
+  }
+  const docs = [];
+  for (const url of docUrls) {
+    const result = await fetchConfluencePage(url);
+    if (typeof result === "string") {
+      return {
+        content: [{ type: "text", text: `Failed to fetch doc: ${result}` }],
+        details: { pipeline: "jira-issues", stages: [] },
+        isError: true
+      };
+    }
+    docs.push(result);
+  }
+  let exampleSection = "";
+  if (exampleUrl) {
+    const result = await fetchConfluencePage(exampleUrl);
+    if (typeof result === "string") {
+      return {
+        content: [{ type: "text", text: `Failed to fetch example: ${result}` }],
+        details: { pipeline: "jira-issues", stages: [] },
+        isError: true
+      };
+    }
+    const page = result;
+    exampleSection = `
+
+EXAMPLE TICKET (match this format):
+Title: ${page.title}
+
+${page.body}`;
+  }
+  const docSections = docs.map((d, i) => `DOCUMENT ${i + 1}: "${d.title}"
+
+${d.body}`).join("\n\n---\n\n");
+  const stages = [emptyStage("jira-issue-creator")];
+  const opts = { agentsDir: AGENTS_DIR, cwd, signal, stages, pipeline: "jira-issues", onUpdate };
+  const task = `Decompose the following PM documents into vertical-slice Jira issues.
+
+${docSections}${exampleSection}
+
+${!exampleUrl ? "No example ticket was provided. Use standard format: Summary, Description, Acceptance Criteria." : ""}
+
+Read the writing-style skill before writing any issue content.`;
+  await runAgent("jira-issue-creator", task, { ...opts, tools: TOOLS_ALL });
+  return {
+    content: [{ type: "text", text: "Jira issue creation complete." }],
+    details: { pipeline: "jira-issues", stages }
+  };
+}
+
 // src/pipelines/prd-qa.ts
 import * as fs5 from "fs";
 async function runPrdQa(cwd, maxIterations, signal, onUpdate, ctx) {
@@ -435,7 +616,7 @@ Stderr: ${criticResult.stderr.slice(0, 300)}` }],
         };
       }
       return {
-        content: [{ type: "text", text: "PRD refinement complete. Ready for /create-issues." }],
+        content: [{ type: "text", text: "PRD refinement complete. Ready for /create-gh-issues." }],
         details: { pipeline: "prd-qa", stages }
       };
     }
@@ -516,10 +697,15 @@ function formatUsage(usage, model) {
 }
 var ForgeflowPmParams = Type.Object({
   pipeline: Type.String({
-    description: 'Which pipeline to run: "continue", "prd-qa", "create-issues", or "create-issue"'
+    description: 'Which pipeline to run: "continue", "prd-qa", "create-gh-issues", "create-gh-issue", "investigate", or "jira-issues"'
   }),
   maxIterations: Type.Optional(Type.Number({ description: "Max iterations for prd-qa (default 10)" })),
-  issue: Type.Optional(Type.String({ description: "Feature idea for create-issue, or description for continue" }))
+  issue: Type.Optional(
+    Type.String({ description: "Feature idea for create-gh-issue, description for continue/investigate" })
+  ),
+  template: Type.Optional(Type.String({ description: "Confluence URL for a template (investigate)" })),
+  docs: Type.Optional(Type.String({ description: "Comma-separated Confluence URLs for PM documents (jira-issues)" })),
+  example: Type.Optional(Type.String({ description: "Confluence/Jira URL for an example ticket (jira-issues)" }))
 });
 function registerForgeflowPmTool(pi) {
   pi.registerTool({
@@ -527,8 +713,10 @@ function registerForgeflowPmTool(pi) {
     label: "Forgeflow PM",
     description: [
       "Run forgeflow PM pipelines: continue (update PRD Done/Next\u2192QA\u2192create issues for next phase),",
-      "prd-qa (refine PRD), create-issues (decompose PRD into GitHub issues),",
-      "create-issue (single issue from a feature idea).",
+      "prd-qa (refine PRD), create-gh-issues (decompose PRD into GitHub issues),",
+      "create-gh-issue (single issue from a feature idea),",
+      "investigate (spike/RFC using codebase exploration + optional Confluence template),",
+      "jira-issues (decompose Confluence PM docs into Jira issues).",
       "Each pipeline spawns specialized sub-agents with isolated context."
     ].join(" "),
     parameters: ForgeflowPmParams,
@@ -542,16 +730,22 @@ function registerForgeflowPmTool(pi) {
             return await runContinue(cwd, params.issue ?? "", params.maxIterations ?? 10, sig, onUpdate, ctx);
           case "prd-qa":
             return await runPrdQa(cwd, params.maxIterations ?? 10, sig, onUpdate, ctx);
-          case "create-issues":
+          case "create-gh-issues":
             return await runCreateIssues(cwd, sig, onUpdate, ctx);
-          case "create-issue":
+          case "create-gh-issue":
             return await runCreateIssue(cwd, params.issue ?? "", sig, onUpdate, ctx);
+          case "investigate":
+            return await runInvestigate(cwd, params.issue ?? "", params.template ?? "", sig, onUpdate, ctx);
+          case "jira-issues": {
+            const docUrls = (params.docs ?? "").split(",").map((u) => u.trim()).filter(Boolean);
+            return await runJiraIssues(cwd, docUrls, params.example ?? "", sig, onUpdate, ctx);
+          }
           default:
             return {
               content: [
                 {
                   type: "text",
-                  text: `Unknown pipeline: ${params.pipeline}. Use: continue, prd-qa, create-issues, create-issue`
+                  text: `Unknown pipeline: ${params.pipeline}. Use: continue, prd-qa, create-gh-issues, create-gh-issue, investigate, jira-issues`
                 }
               ],
               details: { pipeline: params.pipeline, stages: [] }
@@ -649,6 +843,19 @@ function renderCollapsed(details, theme) {
 function stageIcon(stage, theme) {
   return stage.status === "done" ? theme.fg("success", "\u2713") : stage.status === "running" ? theme.fg("warning", "\u27F3") : stage.status === "failed" ? theme.fg("error", "\u2717") : theme.fg("muted", "\u25CB");
 }
+function parseInvestigateArgs(args) {
+  const templateMatch = args.match(/--template\s+(\S+)/);
+  const template = templateMatch ? templateMatch[1] ?? "" : "";
+  const description = args.replace(/--template\s+\S+/, "").trim().replace(/^"(.*)"$/, "$1");
+  return { description, template };
+}
+function parseJiraIssuesArgs(args) {
+  const exampleMatch = args.match(/--example\s+(\S+)/);
+  const example = exampleMatch ? exampleMatch[1] ?? "" : "";
+  const rest = args.replace(/--example\s+\S+/, "").trim();
+  const docs = rest.split(/\s+/).filter(Boolean);
+  return { docs, example };
+}
 var extension = (pi) => {
   registerForgeflowPmTool(pi);
   pi.registerCommand("continue", {
@@ -670,21 +877,40 @@ var extension = (pi) => {
       );
     }
   });
-  pi.registerCommand("create-issues", {
+  pi.registerCommand("create-gh-issues", {
     description: "Decompose PRD.md into vertical-slice GitHub issues",
     handler: async () => {
-      pi.sendUserMessage(`Call the forgeflow-pm tool now with these exact parameters: pipeline="create-issues".`);
+      pi.sendUserMessage(`Call the forgeflow-pm tool now with these exact parameters: pipeline="create-gh-issues".`);
     }
   });
-  pi.registerCommand("create-issue", {
+  pi.registerCommand("create-gh-issue", {
     description: "Create a single GitHub issue from a feature idea",
     handler: async (args) => {
-      if (!args.trim()) {
-        pi.sendUserMessage('I need a feature idea. Usage: /create-issue "Add user authentication"');
-        return;
-      }
+      const issuePart = args.trim() ? `, issue="${args.trim()}"` : "";
+      pi.sendUserMessage(
+        `Call the forgeflow-pm tool now with these exact parameters: pipeline="create-gh-issue"${issuePart}. Do not interpret the issue text \u2014 pass it as-is.`
+      );
+    }
+  });
+  pi.registerCommand("investigate", {
+    description: "Spike or RFC: explore codebase + web, fill a Confluence template. Usage: /investigate [description] [--template <confluence-url>]",
+    handler: async (args) => {
+      const { description, template } = parseInvestigateArgs(args);
+      const issuePart = description ? `, issue="${description}"` : "";
+      const templatePart = template ? `, template="${template}"` : "";
+      pi.sendUserMessage(
+        `Call the forgeflow-pm tool now with these exact parameters: pipeline="investigate"${issuePart}${templatePart}. Do not interpret the description \u2014 pass it as-is.`
+      );
+    }
+  });
+  pi.registerCommand("jira-issues", {
+    description: "Decompose Confluence PM docs into Jira issues. Usage: /jira-issues [confluence-url] [confluence-url...] [--example <confluence-url>]",
+    handler: async (args) => {
+      const { docs, example } = parseJiraIssuesArgs(args);
+      const docsPart = docs.length > 0 ? `, docs="${docs.join(",")}"` : "";
+      const examplePart = example ? `, example="${example}"` : "";
       pi.sendUserMessage(
-        `Call the forgeflow-pm tool now with these exact parameters: pipeline="create-issue", issue="${args.trim()}". Do not interpret the issue text \u2014 pass it as-is.`
+        `Call the forgeflow-pm tool now with these exact parameters: pipeline="jira-issues"${docsPart}${examplePart}. Do not interpret the URLs \u2014 pass them as-is.`
       );
     }
   });

package/package.json

@@ -1,20 +1,26 @@
 {
   "name": "@callumvass/forgeflow-pm",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "PM pipeline for Pi — PRD refinement, issue creation, and continue.",
   "keywords": [
     "pi-package"
   ],
   "license": "MIT",
+  "homepage": "https://github.com/CallumVass/forgeflow#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/callumvass/forgeflow.git",
+    "url": "git+https://github.com/CallumVass/forgeflow.git",
     "directory": "packages/pm"
   },
   "publishConfig": {
     "provenance": true
   },
+  "files": [
+    "extensions",
+    "agents",
+    "skills"
+  ],
   "pi": {
     "extensions": [
       "./extensions"

package/skills/writing-style/SKILL.md

@@ -0,0 +1,33 @@
+# Writing Style
+
+All written output must follow these rules. No exceptions.
+
+## Language
+
+- British English throughout (favour, colour, organisation, analyse, behaviour).
+- Spell out acronyms on first use only if the audience wouldn't know them.
+
+## Tone
+
+- Extremely concise. Every sentence earns its place.
+- Direct and confident. State what is, not what might be.
+- Write like a senior engineer's internal doc — not a blog post, not a sales pitch.
+
+## Anti-patterns — never do these
+
+- No em dashes (—). Use commas, full stops, or restructure.
+- No "Consider...", "It's worth noting...", "It should be noted...", "Importantly,...".
+- No hedging: "might want to", "could potentially", "it may be beneficial".
+- No filler transitions: "Furthermore", "Additionally", "Moreover", "In conclusion".
+- No rhetorical questions.
+- No bullet points that start with the same word repeatedly.
+- No summarising what was just said. Say it once.
+- No emojis.
+
+## Structure
+
+- Lead with the answer or recommendation, not the reasoning.
+- Use short paragraphs (2-3 sentences max).
+- Use headings to structure, not to decorate.
+- Tables over prose when comparing options.
+- Code snippets only when they clarify something prose cannot.