@brainervirus/workit-core 0.4.0

package/src/tools/rules.ts

@@ -0,0 +1,30 @@
+import { tool } from "@opencode-ai/plugin";
+import { fail, ok } from "../core";
+import { listRules, writeRule, type CanonicalRule } from "../core/rules";
+
+const output = (value: unknown) => JSON.stringify(value, null, 2);
+
+export function createRuleTools() {
+  return {
+    workflow_rule_list: tool({
+      description: "List canonical rules (config) with platforms and source",
+      args: {},
+      execute: async () => output(ok({ rules: listRules() })),
+    }),
+    workflow_rule_edit: tool({
+      description: "Write a canonical rule to the toolkit config dir (agent-assisted)",
+      args: {
+        name: tool.schema.string(),
+        description: tool.schema.string(),
+        platforms: tool.schema.array(tool.schema.enum(["cursor", "opencode"])),
+        body: tool.schema.string(),
+        confirmed: tool.schema.boolean(),
+      },
+      execute: async ({ name, description, platforms, body, confirmed }) => {
+        const rule: CanonicalRule = { name, description, platforms, body };
+        const result = writeRule(rule, confirmed);
+        return output(result.ok ? ok(result) : fail(result.error));
+      },
+    }),
+  };
+}

package/src/tools/sdd.ts

@@ -0,0 +1,189 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { tool, type ToolContext } from "@opencode-ai/plugin";
+import { fail, ok, resolveGitRevision, resolveInside } from "../core";
+import { resolveBranch, docsBranch } from "../core/branch";
+import { docsValidate } from "../core/docs-validate";
+import { parsePlanTasks, resolveHandoffBranch } from "../core/plan-tasks";
+import {
+  sddAppendProgress, sddContext, sddReviewPackage, sddTaskBrief,
+} from "../core/sdd";
+import { WorkflowStateStore } from "../state";
+
+const output = (value: unknown) => JSON.stringify(value, null, 2);
+const requireConfirmed = (confirmed: boolean) => confirmed === true
+  ? null
+  : output(fail("confirmed: true required"));
+
+const relativePath = (root: string, candidate: string) => {
+  if (path.isAbsolute(candidate)) throw new Error("path must be repository-relative");
+  resolveInside(root, candidate);
+  return candidate;
+};
+
+const normalize = (value: Record<string, unknown>) => {
+  if (value.error) return fail(String(value.error));
+  if (value.ok === false) return fail("legacy operation reported failure");
+  const { ok: _legacyOk, ...data } = value;
+  return ok(data);
+};
+
+const invoke = (operation: () => Record<string, unknown>) => {
+  try {
+    return output(normalize(operation()));
+  } catch (error) {
+    return output(fail(error instanceof Error ? error.message : "workflow operation failed"));
+  }
+};
+
+const planPaths = (root: string, planPath: string, suppliedSpecPath?: string) => {
+  const resolved = resolveInside(root, planPath);
+  const match = readFileSync(resolved, "utf8").match(/^\*\*Spec:\*\*\s*(?:`([^`]+)`|(\S+))/m);
+  const spec_path = suppliedSpecPath ?? match?.[1] ?? match?.[2] ?? "";
+  if (spec_path) relativePath(root, spec_path);
+  return {
+    spec_path,
+    plan_path: planPath,
+    sdd_dir: path.posix.join("docs", path.basename(path.dirname(planPath)), "sdd"),
+  };
+};
+
+export function createSddTools(state: WorkflowStateStore) {
+  const record = (context: ToolContext, data: Record<string, unknown>) => state.set(context.sessionID, {
+    spec: String(data.spec_path ?? ""),
+    plan: String(data.plan_path ?? ""),
+    sdd: String(data.sdd_dir ?? ""),
+  });
+
+  return {
+    workflow_docs_branch: tool({
+      description: "Resolve branch for spec/plan authors: keep current feature|bugfix or create from develop",
+      args: {
+        plan_path: tool.schema.string().optional(),
+        kind: tool.schema.enum(["feature", "bugfix"]).optional(),
+      },
+      execute: async ({ plan_path, kind }, context) => invoke(() => {
+        if (plan_path) relativePath(context.directory, plan_path);
+        return docsBranch({
+          plan_path,
+          kind,
+          workspace_root: context.directory,
+        }) as Record<string, unknown>;
+      }),
+    }),
+    workflow_docs_validate: tool({
+      description: "Hard-fail validate spec/plan headers, link, branch, task order; returns quality findings (hard/warning)",
+      args: {
+        spec_path: tool.schema.string(),
+        plan_path: tool.schema.string(),
+      },
+      execute: async ({ spec_path, plan_path }, context) => invoke(() => {
+        relativePath(context.directory, spec_path);
+        relativePath(context.directory, plan_path);
+        const result = docsValidate({
+          spec_path,
+          plan_path,
+          workspace_root: context.directory,
+        }) as Record<string, unknown>;
+        if (result.error) return result;
+        if (result.ok === false) return result;
+        return result;
+      }),
+    }),
+    workflow_plan_tasks: tool({
+      description: "Parse top-level tasks from a workflow plan",
+      args: { plan_path: tool.schema.string(), spec_path: tool.schema.string().optional() },
+      execute: async ({ plan_path, spec_path }, context) => invoke(() => {
+        relativePath(context.directory, plan_path);
+        const paths = planPaths(context.directory, plan_path, spec_path);
+        const parsed = parsePlanTasks(plan_path, context.directory) as Record<string, unknown>;
+        if (parsed.error) return parsed;
+        const branch = paths.spec_path
+          ? resolveHandoffBranch(paths.spec_path, plan_path, context.directory) as Record<string, unknown>
+          : {};
+        if (branch.error) return branch;
+        const data = { ...parsed, ...paths, ...branch };
+        record(context, data);
+        return data;
+      }),
+    }),
+    workflow_resolve_branch: tool({
+      description: "Resolve a branch from repository spec and plan metadata",
+      args: { spec_path: tool.schema.string(), plan_path: tool.schema.string() },
+      execute: async ({ spec_path, plan_path }, context) => invoke(() => {
+        relativePath(context.directory, spec_path);
+        relativePath(context.directory, plan_path);
+        return resolveBranch({ spec_path, plan_path, workspace_root: context.directory });
+      }),
+    }),
+    workflow_sdd_context: tool({
+      description: "Resolve the SDD workspace and progress ledger",
+      args: { plan_path: tool.schema.string() },
+      execute: async ({ plan_path }, context) => invoke(() => {
+        relativePath(context.directory, plan_path);
+        const parsed = sddContext({ slug: undefined, plan_path, workspace_root: context.directory }) as Record<string, unknown>;
+        if (parsed.error) return parsed;
+        const todos = Array.isArray(parsed.todos)
+          ? parsed.todos.map((todo: Record<string, unknown>) => todo.status === "in_progress"
+            ? { ...todo, status: "pending" }
+            : todo)
+          : [];
+        const data = { ...parsed, todos, ...planPaths(context.directory, plan_path), sdd_dir: parsed.sdd_dir };
+        record(context, data);
+        return data;
+      }),
+    }),
+    workflow_sdd_task_brief: tool({
+      description: "Write a confirmed task brief",
+      args: {
+        confirmed: tool.schema.boolean(),
+        sdd_dir: tool.schema.string(),
+        task_id: tool.schema.number(),
+        section_text: tool.schema.string(),
+      },
+      execute: async ({ confirmed, sdd_dir, task_id, section_text }, context) => {
+        const rejected = requireConfirmed(confirmed);
+        if (rejected) return rejected;
+        return invoke(() => {
+          relativePath(context.directory, sdd_dir);
+          return sddTaskBrief({ sdd_dir, task_id, section_text, workspace_root: context.directory });
+        });
+      },
+    }),
+    workflow_sdd_review_package: tool({
+      description: "Write a confirmed task review diff",
+      args: {
+        confirmed: tool.schema.boolean(),
+        sdd_dir: tool.schema.string(),
+        base_sha: tool.schema.string(),
+        head_sha: tool.schema.string(),
+      },
+      execute: async ({ confirmed, sdd_dir, base_sha, head_sha }, context) => {
+        const rejected = requireConfirmed(confirmed);
+        if (rejected) return rejected;
+        return invoke(() => {
+          relativePath(context.directory, sdd_dir);
+          resolveGitRevision(context.directory, base_sha);
+          resolveGitRevision(context.directory, head_sha);
+          return sddReviewPackage({ sdd_dir, base_sha, head_sha, workspace_root: context.directory });
+        });
+      },
+    }),
+    workflow_sdd_append_progress: tool({
+      description: "Append one confirmed validated SDD progress line",
+      args: {
+        confirmed: tool.schema.boolean(),
+        progress_path: tool.schema.string(),
+        line: tool.schema.string(),
+      },
+      execute: async ({ confirmed, progress_path, line }, context) => {
+        const rejected = requireConfirmed(confirmed);
+        if (rejected) return rejected;
+        return invoke(() => {
+          relativePath(context.directory, progress_path);
+          return sddAppendProgress({ progress_path, line, workspace_root: context.directory });
+        });
+      },
+    }),
+  };
+}

package/src/tools/templates.ts

@@ -0,0 +1,27 @@
+import { tool } from "@opencode-ai/plugin";
+import { fail, ok } from "../core";
+import { listTemplates, writeTemplate, type TemplateName } from "../core/templates";
+
+const output = (value: unknown) => JSON.stringify(value, null, 2);
+
+export function createTemplateTools() {
+  return {
+    workflow_template_list: tool({
+      description: "List editable templates (issue-update, greeting, headers) with their source",
+      args: {},
+      execute: async () => output(ok({ templates: listTemplates() })),
+    }),
+    workflow_template_edit: tool({
+      description: "Write an edited template to the toolkit config dir (agent-assisted)",
+      args: {
+        name: tool.schema.enum(["issue-update", "greeting", "headers"]),
+        content: tool.schema.string(),
+        confirmed: tool.schema.boolean(),
+      },
+      execute: async ({ name, content, confirmed }) => {
+        const result = writeTemplate(name as TemplateName, content, confirmed);
+        return output(result.ok ? ok(result) : fail(result.error));
+      },
+    }),
+  };
+}

package/src/tools/youtrack.ts

@@ -0,0 +1,356 @@
+import { readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { tool, type ToolContext } from "@opencode-ai/plugin";
+import { fail, ok, resolveInside, type Result } from "../core";
+import { configGuardError, describeConfigGaps } from "../core/config-guard";
+import {
+  buildDraft as legacyBuildDraft,
+  context as legacyContext,
+  logTime as legacyLogTime,
+  parseDuration as legacyParseDuration,
+  parseIssueRef,
+  postUpdate as legacyPostUpdate,
+  verifyYouTrackToken,
+} from "../core/youtrack";
+
+const ISSUE_RE = /^[A-Z]+-\d+$/;
+const output = (value: unknown) => JSON.stringify(value, null, 2);
+const message = (error: unknown) => error instanceof Error ? error.message : String(error);
+
+// Both override names point at the config dir itself, same precedence as
+// src/core/config.ts and scripts/init/status.sh: WORKFLOW_TOOLKIT_CONFIG → WORKFLOW_TOOLKIT_CONFIG_DIR → XDG.
+export const configPath = (env: NodeJS.ProcessEnv = process.env, home = os.homedir()) =>
+  path.join(
+    env.WORKFLOW_TOOLKIT_CONFIG
+    ?? env.WORKFLOW_TOOLKIT_CONFIG_DIR
+    ?? path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "workflow-toolkit"),
+    "youtrack.json",
+  );
+
+export function readCredentials(env: NodeJS.ProcessEnv = process.env, home = os.homedir()) {
+  const resolvedConfig = configPath(env, home);
+  const config = JSON.parse(readFileSync(resolvedConfig, "utf8")) as { tokenFile?: string };
+  const tokenFile = config.tokenFile ?? "youtrack.token";
+  const tokenPath = path.resolve(path.dirname(resolvedConfig), tokenFile.replace(/^~(?=\/)/, home));
+  if (process.platform !== "win32" && (statSync(tokenPath).mode & 0o777) !== 0o600) throw new Error("youtrack.token mode must be 0600");
+  const token = readFileSync(tokenPath, "utf8").trim();
+  if (!token) throw new Error("youtrack.token is empty");
+  return { configPath: resolvedConfig, token };
+}
+
+export const redact = (text: string, token: string) =>
+  token ? text.split(token).join("[REDACTED]") : text;
+
+type MaybePromise<T> = T | Promise<T>;
+type LegacyValue = Record<string, unknown> | void;
+export type NotApplied = { ok: false; error: string; outcome: "not_applied" };
+
+export type YouTrackOperations = {
+  verifyToken(): MaybePromise<LegacyValue>;
+  context(input: Record<string, unknown>): MaybePromise<LegacyValue>;
+  parseDuration(text: string, workspaceRoot: string): MaybePromise<LegacyValue>;
+  postComment(issueId: string, markdown: string, workspaceRoot?: string): MaybePromise<LegacyValue>;
+  logTime(input: Record<string, unknown>): MaybePromise<LegacyValue>;
+};
+
+const unwrap = (value: LegacyValue) => {
+  if (!value) return {};
+  if (value.error) throw new Error(String(value.error));
+  if (value.ok === false) throw new Error(String(value.error ?? "YouTrack operation failed"));
+  return (value.data as Record<string, unknown> | undefined) ?? value;
+};
+
+const defaultOperations: YouTrackOperations = {
+  verifyToken: () => unwrap(verifyYouTrackToken()),
+  context: (input) => legacyContext(input as never),
+  parseDuration: (text, workspaceRoot) => legacyParseDuration(text, workspaceRoot),
+  postComment: (issueId, markdown, workspaceRoot) => legacyPostUpdate({
+    confirmed: true, issueId, markdown, workspace_root: workspaceRoot,
+  } as never),
+  logTime: (input) => legacyLogTime(input as never),
+};
+
+type PostInput = {
+  confirmed: boolean;
+  issueId: string;
+  markdown: string;
+  minutes?: number;
+  workspace_root?: string;
+};
+
+type PostData = {
+  issueId: string;
+  postedComment: boolean;
+  loggedMinutes: number;
+  outcome?: "unknown" | "not_applied";
+  instructions?: string;
+  retry?: "workflow_youtrack_post" | "workflow_youtrack_log_time";
+};
+
+const notApplied = (value: LegacyValue): value is NotApplied =>
+  value?.ok === false && value.outcome === "not_applied";
+
+const withWriteFlag = async <T>(fn: () => Promise<T>): Promise<T> => {
+  const previous = process.env.WORKFLOW_YT_WRITE;
+  process.env.WORKFLOW_YT_WRITE = "1";
+  try {
+    return await fn();
+  } finally {
+    if (previous === undefined) delete process.env.WORKFLOW_YT_WRITE;
+    else process.env.WORKFLOW_YT_WRITE = previous;
+  }
+};
+
+export async function postUpdate(
+  input: PostInput,
+  operations: Pick<YouTrackOperations, "postComment" | "logTime"> = defaultOperations,
+): Promise<Result<PostData>> {
+  if (input.confirmed !== true) return fail("confirmed: true required");
+  if (!ISSUE_RE.test(input.issueId)) return fail("invalid issueId");
+  if (!input.markdown?.trim()) return fail("markdown required");
+  if (input.minutes != null && input.minutes <= 0) return fail("minutes must be positive");
+
+  try {
+    const comment = await operations.postComment(input.issueId, input.markdown, input.workspace_root);
+    if (notApplied(comment)) return fail(comment.error, {
+      issueId: input.issueId, postedComment: false, loggedMinutes: 0,
+      outcome: "not_applied", retry: "workflow_youtrack_post",
+    });
+    unwrap(comment);
+  } catch (error) {
+    return fail(message(error), {
+      issueId: input.issueId, postedComment: false, loggedMinutes: 0, outcome: "unknown",
+      instructions: "Check YouTrack comments manually; do not retry while the outcome is unknown.",
+    });
+  }
+
+  if (input.minutes != null) {
+    try {
+      const time = await operations.logTime({
+        issueId: input.issueId,
+        minutes: input.minutes,
+        text: "workit update",
+        workspace_root: input.workspace_root,
+      });
+      if (notApplied(time)) return fail(time.error, {
+        issueId: input.issueId, postedComment: true, loggedMinutes: 0,
+        outcome: "not_applied", retry: "workflow_youtrack_log_time",
+      });
+      unwrap(time);
+    } catch (error) {
+      return fail(message(error), {
+        issueId: input.issueId, postedComment: true, loggedMinutes: 0, outcome: "unknown",
+        instructions: "Check YouTrack time entries manually; do not retry while the outcome is unknown.",
+      });
+    }
+  }
+
+  return ok({
+    issueId: input.issueId,
+    postedComment: true,
+    loggedMinutes: input.minutes ?? 0,
+  });
+}
+
+export async function logTimeUpdate(
+  input: Record<string, unknown>,
+  operation: Pick<YouTrackOperations, "logTime"> = defaultOperations,
+): Promise<Result<Record<string, unknown>>> {
+  try {
+    const value = await operation.logTime(input);
+    if (notApplied(value)) return fail(value.error, {
+      issueId: input.issueId, loggedMinutes: 0, outcome: "not_applied",
+      retry: "workflow_youtrack_log_time",
+    });
+    return ok(unwrap(value));
+  } catch (error) {
+    return fail(message(error), {
+      issueId: input.issueId, loggedMinutes: 0, outcome: "unknown",
+      instructions: "Check YouTrack time entries manually; do not retry while the outcome is unknown.",
+    });
+  }
+}
+
+export function normalizeContext(value: LegacyValue, mode?: string): LegacyValue {
+  if (!value || mode !== "meetings") return value;
+  const config = value.config as Record<string, unknown> | undefined;
+  const issue = String(config?.meetingIssue || "IRPT-12");
+  const { meetingIssues: _meetingIssues, ...singleMeetingConfig } = config ?? {};
+  const options = Array.isArray(value.meetingOptions)
+    ? value.meetingOptions as Array<Record<string, unknown>>
+    : [];
+  const selected = options.find((option) => option.issue === issue) ?? {
+    key: "general", issue, label: issue, workItemText: "Reuniones",
+  };
+  return {
+    ...value,
+    config: singleMeetingConfig,
+    meetingOptions: [selected],
+    requiresMeetingChoice: false,
+    issueId: issue,
+    workItemText: selected.workItemText ?? "Reuniones",
+  };
+}
+
+const standardResult = (value: LegacyValue, token = "") => {
+  try {
+    const data = unwrap(value);
+    const { ok: _legacyOk, ...normalized } = data;
+    return ok(normalized);
+  } catch (error) {
+    return fail(redact(message(error), token));
+  }
+};
+
+const invoke = async (operation: () => MaybePromise<LegacyValue>, token = "") => {
+  try {
+    return output(standardResult(await operation(), token));
+  } catch (error) {
+    return output(fail(redact(message(error), token)));
+  }
+};
+
+const credentials = () => readCredentials();
+const configGap = () => {
+  const { missing } = describeConfigGaps(["youtrack_json", "youtrack_token"]);
+  return missing.length > 0 ? output(fail(configGuardError(missing))) : null;
+};
+const requireConfirmed = (confirmed: boolean) => confirmed === true
+  ? null
+  : output(fail("confirmed: true required"));
+
+const rejectedTimeInput = (issueId: string, minutes: number) => {
+  const error = !ISSUE_RE.test(issueId)
+    ? "invalid issueId"
+    : !Number.isFinite(minutes) || minutes <= 0
+      ? "minutes must be positive"
+      : null;
+  return error ? output(fail(error, {
+    issueId, loggedMinutes: 0, outcome: "not_applied",
+    retry: "workflow_youtrack_log_time",
+    instructions: "Correct the invalid input, then retry workflow_youtrack_log_time once.",
+  })) : null;
+};
+
+export function createYouTrackTools(operations: YouTrackOperations = defaultOperations) {
+  return {
+    workflow_youtrack_verify_token: tool({
+      description: "Verify the configured YouTrack token with a read-only request",
+      args: {},
+      execute: async () => {
+        let token = "";
+        try { token = credentials().token; } catch (error) {
+          const gap = configGap();
+          if (gap) return gap;
+          return output(fail(message(error)));
+        }
+        return invoke(() => operations.verifyToken(), token);
+      },
+    }),
+    workflow_youtrack_parse_issue: tool({
+      description: "Parse an existing YouTrack issue URL or id",
+      args: { issue_ref: tool.schema.string() },
+      execute: async ({ issue_ref }) => invoke(() => parseIssueRef(issue_ref)),
+    }),
+    workflow_youtrack_context: tool({
+      description: "Load YouTrack context for the configured meeting issue or an existing task issue",
+      args: {
+        mode: tool.schema.enum(["meetings", "task"]).optional(),
+        issue_id: tool.schema.string().optional(),
+        issue_url: tool.schema.string().optional(),
+        issue_ref: tool.schema.string().optional(),
+        spec_path: tool.schema.string().optional(),
+        plan_path: tool.schema.string().optional(),
+      },
+      execute: async (input, context) => {
+        try {
+          for (const candidate of [input.spec_path, input.plan_path].filter(Boolean) as string[]) {
+            if (path.isAbsolute(candidate)) throw new Error("path must be repository-relative");
+            resolveInside(context.directory, candidate);
+          }
+        } catch (error) {
+          const detail = message(error);
+          return output(fail(detail.includes("repository-relative") ? detail : `path must be repository-relative: ${detail}`));
+        }
+        let token = "";
+        try { token = credentials().token; } catch (error) {
+          const gap = configGap();
+          if (gap) return gap;
+          return output(fail(message(error)));
+        }
+        return invoke(async () => normalizeContext(
+          await operations.context({ ...input, workspace_root: context.directory }), input.mode,
+        ), token);
+      },
+    }),
+    workflow_youtrack_parse_duration: tool({
+      description: "Parse duration text into integer minutes",
+      args: { text: tool.schema.string() },
+      execute: async ({ text }, context) => invoke(() => operations.parseDuration(text, context.directory)),
+    }),
+    workflow_youtrack_draft: tool({
+      description: "Build an es-CL update comment without posting it",
+      args: {
+        issueId: tool.schema.string(),
+        userNotes: tool.schema.string(),
+        greeting: tool.schema.string().optional(),
+        projectName: tool.schema.string().optional(),
+        includeProjectOpener: tool.schema.boolean().optional(),
+        includeFacts: tool.schema.boolean().optional(),
+        facts: tool.schema.object({
+          progress_excerpt: tool.schema.array(tool.schema.string()).optional(),
+          git_commits: tool.schema.array(tool.schema.string()).optional(),
+        }).optional(),
+      },
+      execute: async (input) => invoke(() => legacyBuildDraft(input as never)),
+    }),
+    workflow_youtrack_log_time: tool({
+      description: "Log confirmed time on an existing YouTrack issue without posting a comment",
+      args: {
+        confirmed: tool.schema.boolean(),
+        issueId: tool.schema.string(),
+        minutes: tool.schema.number(),
+        text: tool.schema.string().optional(),
+        dateMs: tool.schema.number().optional(),
+      },
+      execute: async ({ confirmed, ...input }, context: ToolContext) => {
+        const rejected = requireConfirmed(confirmed);
+        if (rejected) return rejected;
+        const invalid = rejectedTimeInput(input.issueId, input.minutes);
+        if (invalid) return invalid;
+        let token = "";
+        try { token = credentials().token; } catch (error) {
+          const gap = configGap();
+          if (gap) return gap;
+          return output(fail(message(error)));
+        }
+        const result = await withWriteFlag(() =>
+          logTimeUpdate({ ...input, workspace_root: context.directory }, operations));
+        return output(result.ok ? result : { ...result, error: redact(result.error, token) });
+      },
+    }),
+    workflow_youtrack_post: tool({
+      description: "Post a confirmed es-CL comment, then optionally log time",
+      args: {
+        confirmed: tool.schema.boolean(),
+        issueId: tool.schema.string(),
+        markdown: tool.schema.string(),
+        minutes: tool.schema.number().optional(),
+      },
+      execute: async (input, context: ToolContext) => {
+        const rejected = requireConfirmed(input.confirmed);
+        if (rejected) return rejected;
+        let token = "";
+        try { token = credentials().token; } catch (error) {
+          const gap = configGap();
+          if (gap) return gap;
+          return output(fail(message(error)));
+        }
+        const result = await withWriteFlag(() =>
+          postUpdate({ ...input, workspace_root: context.directory }, operations));
+        return output(result.ok ? result : { ...result, error: redact(result.error, token) });
+      },
+    }),
+  };
+}

package/templates/execution-contract.md

@@ -0,0 +1,56 @@
+Load `using-superpowers`, `subagent-driven-development`, `test-driven-development`, and `verification-before-completion` through OpenCode's `skill` tool. Implement the existing plan; do not re-plan.
+
+**Spec:** <SPEC_PATH>
+**Plan:** <PLAN_PATH>
+**Branch:** <BRANCH>
+**SDD:** `<SDD_DIR>`
+
+## Hard gates
+
+- The parent is coordinator-only: it does not edit product code or perform delegated exploration.
+- Never use a worktree. Branch changes are in-place through `workflow_branch_setup` on `feature/*` or `bugfix/*`; never commit on protected branches.
+- Tracked state, briefs, ledgers, and review diffs live only under `<SDD_DIR>` in `docs/<slug>/sdd/` and use `workflow_sdd_*` tools.
+- Use native `todowrite` for visible task state as well as the tracked ledger.
+- Use native `question` for branch/stash choices and guarded external mutations; call mutation tools only after approval with `confirmed: true`.
+- Use native `task` with only the built-in `explore` and `general` agents.
+
+## Flow gates (HARD)
+
+- `wk-implement` refuses to run unless the plan is `approved` (flow.json) and the post-plan menu was presented.
+- `wk-handoff` refuses to run unless both spec and plan are `approved`.
+- Sequence is enforced by tools: `workflow_spec_approve` (×2), `workflow_plan_approve` (×2), `workflow_plan_menu` — never skip a step.
+
+## Setup
+
+0. Call `workflow_docs_validate` with the linked spec/plan paths. Hard-fail on any error before todos or branch setup.
+1. Call `workflow_sdd_context` with `<PLAN_PATH>` and initialize `todowrite` from returned tasks.
+2. Call `workflow_plan_tasks`; cache each top-level task's `section_text`.
+3. Mark IDs in `completed_task_ids` completed and never redispatch them.
+4. Call `workflow_resolve_branch`, then show the current branch, target branch, and stash behavior before any in-place checkout/setup mutation.
+5. Always use `question`: for a clean tree ask whether to proceed or cancel; for a dirty tree add the stash choice and describe what will be stashed.
+6. Call `workflow_branch_setup` with `confirmed: true` only after approval.
+
+## Remaining-task loop
+
+For each top-level task absent from `completed_task_ids`:
+
+1. Mark it `in_progress` with `todowrite`.
+2. Create a tracked brief with `workflow_sdd_task_brief` and `confirmed: true`.
+3. Delegate read-only discovery, when needed, to an `explore` agent. Delegate implementation to a fresh `general` agent. Product changes follow TDD.
+4. Create a tracked diff with `workflow_sdd_review_package` and `confirmed: true`.
+5. Delegate spec-compliance review and code-quality review to separate `general` agents.
+6. **Blocking** findings (Critical, Important, or spec-compliance) may trigger at most **two** fix+re-review rounds per task. **Advisory** findings (Minor, style, YAGNI, taste) never pause the loop — append them to `<SDD_DIR>/advisories.md`.
+7. Append the validated ledger entry with `workflow_sdd_append_progress` and `confirmed: true`; mark the todo completed.
+
+## Final gate
+
+Run a separate full-branch code review, then `workflow_verify`. Present the full `<SDD_DIR>/advisories.md` roll-up once, then use native `question` so the user can choose which advisory items to fix, discuss, or discard. Report exact check results and never infer success. Use `workflow_git_context` for a commit preview and load `wk-commit` through `skill` for an approved commit. If tracked state contains a stash reference, preview reapplication through `question`, then call `workflow_branch_setup` with `confirmed: true` after approval.
+
+## Task order
+
+<TASK_LIST>
+
+## Quality gate (HARD)
+
+- Specs/plans are written from `templates/spec-template.md` / `templates/plan-template.md`.
+- After `workflow_docs_validate`, surface `quality` findings (spec scan). Hard findings (missing required section, missing CA-XX) block task start unless the user explicitly waives them. Warnings are advisory.

package/templates/greeting.md

@@ -0,0 +1 @@
+{{greetingText}}

package/templates/headers.md

@@ -0,0 +1,3 @@
+## Adjunto capturas
+
+## Archivos adjuntos

package/templates/hygiene/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2

package/templates/hygiene/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+*.md text
+*.bat text eol=crlf