@yaawn/workflow 0.0.0-stage → 0.3.1

package/agents/skills/yaawn-save-plan/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: yaawn-save-plan
+description: "Save the plan /yaawn-create-plan wrote to .yaawn/plans/yaawn-<issue>-plan.md into the GitHub issue's \"Implementation Plan\" section — open questions, design decisions, implementation steps, and an ELI5 Human Readable summary — and remove the Yaawn: To Be Refined label. Does not execute the plan (use yaawn-implement-plan) or verify it (use yaawn-verify-executed-plan)."
+disable-model-invocation: true
+argument-hint: "[GitHub issue number]"
+metadata:
+  github-repo: https://github.com/markusfalk/yaawn
+  author: markusfalk
+---
+
+Start this skill in a new session. It works only from files and the issue, never from an earlier conversation: the plan is the file `/yaawn-create-plan` left at `.yaawn/plans/yaawn-<issue>-plan.md` in one of the project's git worktrees.
+
+Out of scope: changing the plan, grilling it again, and touching the story or acceptance criteria. To change the plan, run `/yaawn-create-plan` again.
+
+## 1. Find the plan file
+
+```sh
+npx tsx .agents/skills/yaawn-save-plan/scripts/save-plan.ts find [issue]
+```
+
+The plan file may live in another git worktree than the one this session runs in, so the script searches the worktrees in order: the current worktree, the issue's own worktree (the one on branch `yaawn/<issue>`), then the main copy. It prints the issue, the plan file, and the summary path.
+
+- The current worktree holds the plan: it wins.
+- Exactly one other worktree holds it: that plan is used.
+- Several worktrees hold it and the session runs in none of them: the script stops and names their paths — tell the user to run this skill in the one whose plan they want to save. It never picks one silently.
+- No worktree holds it: stop and tell the user to start a new session and run `/yaawn-create-plan <issue>` first. Never rebuild a plan from a conversation.
+- `git worktree list` fails (no git, no repository): only the current directory is searched.
+
+If no issue is given, the script infers it from the `yaawn-<issue>-plan.md` files in `.yaawn/plans/` of the current worktree, every `yaawn/<n>` worktree and the main copy together. Exactly one match: it is used. Several matches: the script lists them — ask which one. No match: ask for the issue number.
+
+## 2. Write the Human Readable summary
+
+Read the plan file and write a **short** "Human Readable" version of it to the summary path step 1 printed — `.yaawn/plans/yaawn-<issue>-human-readable.md` next to the plan file, in the same worktree — following `.agents/output-styles/yaawn-eli5.instructions.md`. Write only the content — no `### Human Readable` heading; the script adds the content under the existing one. Inside the summary, use only `####` or deeper headings — never `#`, `##`, or `###`. The content lands inside the issue's `## Implementation Plan` section, and a shallower heading would restructure the template and truncate the plan `/yaawn-implement-plan` later extracts. The script demotes any heading that is too shallow, so the issue's heading structure never changes.
+
+Explain the **implementation only**. Do not explain the feature; what the user gets is already in the issue's story and acceptance criteria. If applicable, add a mermaid diagram showing the architecture of the plan. Keep the diagram on a conceptual, high level — it is meant to give an overview.
+
+## 3. Preview
+
+```sh
+npx tsx .agents/skills/yaawn-save-plan/scripts/save-plan.ts preview <issue>
+```
+
+The script ([scripts/save-plan.ts](./scripts/save-plan.ts), with the section logic in [scripts/plan-body.ts](./scripts/plan-body.ts)) fetches the issue body fresh and builds the new body: it replaces the content under `### Human Readable`, `### Open Questions`, `### Design Decisions`, `### Files to Change`, and `### LLM Plan` inside `## Implementation Plan`. Each subsection is replaced as a whole block, so re-saving onto an older issue that still carries a `#### Definition of Done` section under `### LLM Plan` drops that stale copy as a side effect — the Definition of Done lives only in `.yaawn/yaawn-definition-of-done.md`. Headings inside the inserted content are demoted below `###`, so the inserted content can never change the issue's heading structure — and re-saving an issue whose plan section an older yaawn broke with `##`-level content repairs it. Nothing outside that section changes — the story and acceptance criteria are never touched. An issue without `## Implementation Plan` (created without a template) gets the section appended with all five subsections. An older issue whose `## Implementation Plan` lacks `### Files to Change` gets that heading inserted right before `### LLM Plan`. It prints whether the issue already has a plan and the diff of the body.
+
+- An error: report it and stop. Any other missing subsection heading means the issue's `## Implementation Plan` is incomplete — the user adds the heading, then runs this skill again.
+- `existing plan: no`: continue with step 4.
+- `existing plan: yes`: summarize the diff in a few lines — which steps, decisions, and questions change — and ask **one** question through the ask tool: overwrite the plan on the issue? Do not grill or reconsider the plan here; the plan file is the reviewed result of `/yaawn-create-plan`. If the user declines, stop.
+
+## 4. Save
+
+```sh
+npx tsx .agents/skills/yaawn-save-plan/scripts/save-plan.ts save <issue>
+```
+
+It writes the body with `gh issue edit --body-file`, then removes the `Yaawn: To Be Refined` label if present — the saved plan is the refinement. When the save changes `### Files to Change` or the `**Depends on:**` line — both feed the implementation grouping — it also removes the issue's `Yaawn: implementation-group-<n>` labels through `/yaawn-implement-plan`'s shared group-label reset; the implementation group no longer holds. If that removal fails, the script prints a warning and the save still succeeds — the next `/yaawn-implement-plan` run resets the labels when it starts.
+
+It then adds the `Yaawn: Ready To Implement` label (creating the label in the repository if missing) when the plan's `### Open Questions` table has no question with an empty Answer and `### Files to Change` lists at least one file. Otherwise it prints why the issue was not marked ready — report that to the user. If adding the label fails, the saved body stays and the script prints a warning; tell the user to add the label manually. Edit the issue body only — never create comments on the issue.
+
+The issue body snapshots (`yaawn-<issue>-body-current.md`, `yaawn-<issue>-body.md`) always go to the current worktree's `.yaawn/plans/`, wherever the plan file lives.
+
+Leave the working files under `.yaawn/plans/` in place — the developer cleans them up manually.
+
+## 5. Hand off
+
+Tell the user: once every issue that belongs in the run has a saved plan, start a new session and run `/yaawn-implement-plan <issue>`.

package/agents/skills/yaawn-save-plan/scripts/plan-body.ts

@@ -0,0 +1,331 @@
+// Pure markdown-section machinery for yaawn-save-plan: finds the
+// "Implementation Plan" section of an issue body and replaces its
+// subsections. No I/O — save-plan.ts reads files and calls gh, this module
+// only computes.
+
+export interface Heading {
+  level: number;
+  title: string;
+  line: number;
+}
+
+export interface LineRange {
+  start: number;
+  end: number;
+}
+
+export interface Section {
+  headingLine: number;
+  contentStart: number;
+  contentEnd: number;
+}
+
+export const implementationPlanTitle = "Implementation Plan";
+export const humanReadableTitle = "Human Readable";
+export const openQuestionsTitle = "Open Questions";
+export const filesToChangeTitle = "Files to Change";
+export const llmPlanTitle = "LLM Plan";
+export const planSubsections = [
+  openQuestionsTitle,
+  "Design Decisions",
+  filesToChangeTitle,
+  llmPlanTitle,
+];
+export const issueSubsections = [humanReadableTitle, ...planSubsections];
+
+const subsectionLevel = 3;
+
+export const headingList = (titles: string[]): string =>
+  titles.map((title) => `### ${title}`).join(", ");
+
+export function toLines(markdown: string): string[] {
+  return markdown.split(/\r?\n/);
+}
+
+function fenceOpening(line: string): string | null {
+  return /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1] ?? null;
+}
+
+function closesFence(line: string, fence: string): boolean {
+  const closing = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(line)?.[1];
+  return (
+    closing !== undefined &&
+    closing[0] === fence[0] &&
+    closing.length >= fence.length
+  );
+}
+
+// Headings inside fenced code blocks (e.g. a "# comment" in a shell snippet)
+// are not section boundaries.
+export function headingsOf(lines: string[]): Heading[] {
+  const headings: Heading[] = [];
+  let fence: string | null = null;
+  lines.forEach((line, index) => {
+    if (fence !== null) {
+      if (closesFence(line, fence)) fence = null;
+      return;
+    }
+    fence = fenceOpening(line);
+    if (fence !== null) return;
+    const match = /^(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
+    if (match) {
+      headings.push({ level: match[1].length, title: match[2], line: index });
+    }
+  });
+  return headings;
+}
+
+export function findSection(
+  lines: string[],
+  level: number,
+  title: string,
+  within: LineRange = { start: 0, end: lines.length },
+): Section | null {
+  const inRange = headingsOf(lines).filter(
+    (heading) => heading.line >= within.start && heading.line < within.end,
+  );
+  const heading = inRange.find(
+    (candidate) => candidate.level === level && candidate.title === title,
+  );
+  if (!heading) return null;
+  const next = inRange.find(
+    (candidate) => candidate.line > heading.line && candidate.level <= level,
+  );
+  return {
+    headingLine: heading.line,
+    contentStart: heading.line + 1,
+    contentEnd: next?.line ?? within.end,
+  };
+}
+
+function contentRange(section: Section): LineRange {
+  return { start: section.contentStart, end: section.contentEnd };
+}
+
+// Content inserted under a ### subsection may only carry headings deeper than
+// the subsection: a heading at level 3 or shallower would end the subsection
+// — or the whole ## Implementation Plan section — and restructure the issue
+// template, so /yaawn-implement-plan would later extract a truncated plan.
+// Shift every heading deeper so the shallowest one lands at minLevel, keeping
+// the content's own hierarchy.
+export function demoteHeadings(markdown: string, minLevel: number): string {
+  const lines = toLines(markdown);
+  const headings = headingsOf(lines);
+  if (headings.length === 0) return markdown;
+  const shallowest = Math.min(...headings.map((heading) => heading.level));
+  const shift = minLevel - shallowest;
+  if (shift <= 0) return markdown;
+  headings.forEach((heading) => {
+    const level = Math.min(6, heading.level + shift);
+    lines[heading.line] =
+      "#".repeat(level) + lines[heading.line].slice(heading.level);
+  });
+  return lines.join("\n");
+}
+
+function fitUnderSubsections(content: Map<string, string>): Map<string, string> {
+  return new Map(
+    [...content].map(([title, value]) => [
+      title,
+      demoteHeadings(value, subsectionLevel + 1),
+    ]),
+  );
+}
+
+// An issue saved by an older yaawn could carry shallow content headings (##
+// or ###) inside the plan, which end the bounded plan range early and hide
+// the later subsections. When that is the case, demote every stray heading
+// below the subsection level — the subsection replacement rewrites their
+// content anyway — so the subsections are found and a re-save restores the
+// template structure. A healthy body is returned unchanged.
+function healedPlanLines(lines: string[], plan: Section): string[] {
+  const bounded = contentRange(plan);
+  const complete = issueSubsections.every(
+    (title) => findSection(lines, 3, title, bounded) !== null,
+  );
+  if (complete) return lines;
+  const healed = [...lines];
+  headingsOf(lines).forEach((heading) => {
+    if (heading.line < plan.contentStart) return;
+    if (heading.level === 3 && issueSubsections.includes(heading.title)) return;
+    if (heading.level > 3) return;
+    healed[heading.line] = "####" + healed[heading.line].slice(heading.level);
+  });
+  return healed;
+}
+
+function appendImplementationPlan(
+  body: string,
+  content: Map<string, string>,
+): string {
+  const subsections = issueSubsections.map(
+    (title) => `### ${title}\n\n${content.get(title)}`,
+  );
+  return [body, `## ${implementationPlanTitle}`, ...subsections].join("\n\n");
+}
+
+function findIssueSubsections(
+  lines: string[],
+  within: LineRange,
+): { title: string; section: Section }[] {
+  const found = issueSubsections.map((title) => ({
+    title,
+    section: findSection(lines, 3, title, within),
+  }));
+  const missing = found.filter(({ section }) => section === null);
+  if (missing.length > 0) {
+    throw new Error(
+      `the issue's "## ${implementationPlanTitle}" lacks: ${headingList(missing.map(({ title }) => title))} — add the heading to the issue, then run again`,
+    );
+  }
+  return found as { title: string; section: Section }[];
+}
+
+function replaceSubsections(
+  lines: string[],
+  within: LineRange,
+  content: Map<string, string>,
+): string[] {
+  const bottomUp = findIssueSubsections(lines, within).sort(
+    (a, b) => b.section.headingLine - a.section.headingLine,
+  );
+  return bottomUp.reduce((result, { title, section }) => {
+    const replacement = ["", ...toLines(content.get(title) ?? ""), ""];
+    return [
+      ...result.slice(0, section.contentStart),
+      ...replacement,
+      ...result.slice(section.contentEnd),
+    ];
+  }, lines);
+}
+
+// Issues created before "### Files to Change" existed get the heading
+// inserted right before "### LLM Plan".
+function withFilesToChangeHeading(
+  lines: string[],
+  within: LineRange,
+): string[] {
+  if (findSection(lines, 3, filesToChangeTitle, within)) return lines;
+  const llmPlan = findSection(lines, 3, llmPlanTitle, within);
+  if (!llmPlan) return lines;
+  return [
+    ...lines.slice(0, llmPlan.headingLine),
+    `### ${filesToChangeTitle}`,
+    "",
+    ...lines.slice(llmPlan.headingLine),
+  ];
+}
+
+export function buildBody(body: string, content: Map<string, string>): string {
+  const safeContent = fitUnderSubsections(content);
+  const originalLines = toLines(body);
+  const originalPlan = findSection(originalLines, 2, implementationPlanTitle);
+  if (!originalPlan) {
+    return `${appendImplementationPlan(body, safeContent).trimEnd()}\n`;
+  }
+  const healed = healedPlanLines(originalLines, originalPlan);
+  const healedPlan = findSection(
+    healed,
+    2,
+    implementationPlanTitle,
+  ) as Section;
+  const lines = withFilesToChangeHeading(healed, contentRange(healedPlan));
+  const plan = findSection(lines, 2, implementationPlanTitle) as Section;
+  const newBody = replaceSubsections(
+    lines,
+    contentRange(plan),
+    safeContent,
+  ).join("\n");
+  return `${newBody.trimEnd()}\n`;
+}
+
+export function ownLlmPlanContent(body: string): string {
+  const lines = toLines(body);
+  const plan = findSection(lines, 2, implementationPlanTitle);
+  if (!plan) return "";
+  const healed = healedPlanLines(lines, plan);
+  const healedPlan = findSection(healed, 2, implementationPlanTitle);
+  if (!healedPlan) return "";
+  const llmPlan = findSection(healed, 3, llmPlanTitle, contentRange(healedPlan));
+  if (!llmPlan) return "";
+  const firstSubheading = headingsOf(healed).find(
+    (heading) =>
+      heading.line > llmPlan.headingLine && heading.line < llmPlan.contentEnd,
+  );
+  return healed
+    .slice(llmPlan.contentStart, firstSubheading?.line ?? llmPlan.contentEnd)
+    .join("\n")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .trim();
+}
+
+export function filesToChangeContent(body: string): string {
+  const lines = toLines(body);
+  const plan = findSection(lines, 2, implementationPlanTitle);
+  if (!plan) return "";
+  const healed = healedPlanLines(lines, plan);
+  const healedPlan = findSection(healed, 2, implementationPlanTitle);
+  if (!healedPlan) return "";
+  const filesToChange = findSection(
+    healed,
+    3,
+    filesToChangeTitle,
+    contentRange(healedPlan),
+  );
+  if (!filesToChange) return "";
+  return healed
+    .slice(filesToChange.contentStart, filesToChange.contentEnd)
+    .join("\n")
+    .trim();
+}
+
+const withoutHtmlComments = (markdown: string): string =>
+  markdown.replace(/<!--[\s\S]*?-->/g, "");
+
+function tableCells(row: string): string[] {
+  return row
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split(/(?<!\\)\|/)
+    .map((cell) => cell.trim());
+}
+
+function columnIndex(header: string[], name: string, fallback: number): number {
+  const index = header.indexOf(name);
+  return index < 0 ? fallback : index;
+}
+
+function countUnansweredQuestions(openQuestions: string): number {
+  const rows = toLines(withoutHtmlComments(openQuestions)).filter((line) =>
+    line.trim().startsWith("|"),
+  );
+  const [header, ...body] = rows.map(tableCells);
+  if (!header) return 0;
+  // Fall back to the template's column layout so an unknown header fails closed.
+  const questionColumn = columnIndex(header, "Questions", 1);
+  const answerColumn = columnIndex(header, "Answer", 3);
+  return body.filter(
+    (cells) =>
+      !cells.every((cell) => /^:?-+:?$/.test(cell)) &&
+      (cells[questionColumn] ?? "") !== "" &&
+      (cells[answerColumn] ?? "") === "",
+  ).length;
+}
+
+function hasFilesToChange(filesToChange: string): boolean {
+  return toLines(withoutHtmlComments(filesToChange)).some((line) =>
+    /^\s*[-*+]\s+\S/.test(line),
+  );
+}
+
+export function readyBlocker(content: Map<string, string>): string | null {
+  const unanswered = countUnansweredQuestions(
+    content.get(openQuestionsTitle) ?? "",
+  );
+  if (unanswered > 0) return `${unanswered} unanswered question(s)`;
+  if (!hasFilesToChange(content.get(filesToChangeTitle) ?? "")) {
+    return `### ${filesToChangeTitle} is empty`;
+  }
+  return null;
+}