@uniqbit/mate-core 0.15.5 → 0.16.0-canary.0

package/src/cli/commands/studio/views/workflow/steps.ts

@@ -0,0 +1,329 @@
+import { CHANGE_PLACEHOLDER } from "../../selection";
+
+export type WorkflowStepKind = "skill" | "review" | "completion" | "optional";
+export type WorkflowStepBadge = "optional" | "skill" | "openspec" | "human-in-loop";
+export type WorkflowProfile = "mate-v1" | "mate-minimal";
+
+export interface WorkflowAlternative {
+  name: string;
+  description: string;
+  prompt: string;
+  copyPrompt: string;
+}
+
+export interface WorkflowStep {
+  kind: WorkflowStepKind;
+  id: string;
+  /** The action the stage performs. */
+  what: string;
+  /** The reason the stage is in the sequence at this position. */
+  why: string;
+  title: string;
+  badges: WorkflowStepBadge[];
+  sessionBreakBefore?: boolean;
+  prompt: string;
+  copyPrompt: string;
+  alternatives?: WorkflowAlternative[];
+}
+
+export interface WorkflowBranch {
+  profile: WorkflowProfile;
+  label: string;
+  description: string;
+  steps: WorkflowStep[];
+}
+
+export interface WorkflowPlan {
+  start: WorkflowStep;
+  branches: WorkflowBranch[];
+  shared: WorkflowStep[];
+  finish: WorkflowStep;
+}
+
+const PRE_EXPLORE_SKILLS = ["mate-interview-me", "mate-grill-me"] as const;
+
+/** The optional post-apply stretch, in presented order, each keyed to the skill that drives it. */
+const SHARED_OPTIONAL_SKILLS = {
+  "show-me": "mate-show-me",
+  simplify: "mate-simplify-code",
+} as const;
+
+type SharedOptionalId = keyof typeof SHARED_OPTIONAL_SKILLS;
+
+function stepPrompt(
+  step: Omit<WorkflowStep, "prompt" | "copyPrompt">,
+  profile?: WorkflowProfile,
+  includeChange = true,
+): string {
+  const changeNote = includeChange ? ` for ${CHANGE_PLACEHOLDER}` : " for";
+  const schemaNote = profile && profile !== "mate-v1" ? ` (use schema: ${profile})` : "";
+
+  switch (step.id) {
+    case "pre-explore":
+      return `/mate-interview-me or /mate-grill-me${changeNote}`;
+    case "explore":
+      return `/openspec-explore${schemaNote}${changeNote}`;
+    case "proposal":
+    case "propose":
+      return `/openspec-propose${schemaNote}${changeNote}`;
+    case "specs":
+    case "design":
+    case "tasks":
+      return `Review ${includeChange ? CHANGE_PLACEHOLDER : ""}/`;
+    case "apply":
+      return `/openspec-apply-change${schemaNote}${changeNote}`;
+    case "show-me":
+      return `/mate-show-me${changeNote}`;
+    case "simplify":
+      return `/mate-simplify-code${changeNote}`;
+    case "archive":
+      return `/openspec-archive-change${changeNote}`;
+    case "finish":
+      return `/mate-artifact-publish${changeNote}`;
+    default:
+      return `Use ${step.title}${schemaNote}${changeNote}`;
+  }
+}
+
+function skillStep(
+  id: string,
+  title: string,
+  what: string,
+  why: string,
+  profile?: WorkflowProfile,
+): WorkflowStep {
+  const step = {
+    kind: "skill" as const,
+    id,
+    title,
+    what,
+    why,
+    badges: ["skill", "openspec"] as WorkflowStepBadge[],
+  };
+  return {
+    ...step,
+    prompt: stepPrompt(step, profile),
+    copyPrompt: stepPrompt(step, profile, false),
+  };
+}
+
+function reviewStep(
+  id: string,
+  title: string,
+  what: string,
+  why: string,
+  profile?: WorkflowProfile,
+): WorkflowStep {
+  const step = {
+    kind: "review" as const,
+    id,
+    title,
+    what,
+    why,
+    badges: ["human-in-loop", "openspec"] as WorkflowStepBadge[],
+  };
+  return {
+    ...step,
+    prompt: stepPrompt(step, profile),
+    copyPrompt: stepPrompt(step, profile, false),
+  };
+}
+
+function optionalStep(
+  id: "pre-explore" | SharedOptionalId,
+  title: string,
+  what: string,
+  why: string,
+  alternatives: WorkflowAlternative[] = [],
+): WorkflowStep {
+  const step = {
+    kind: "optional" as const,
+    id,
+    title,
+    what,
+    why,
+    badges: ["optional", "skill"] as WorkflowStepBadge[],
+  };
+  return {
+    ...step,
+    prompt: stepPrompt(step),
+    copyPrompt: stepPrompt(step, undefined, false),
+    ...(id === "pre-explore" || alternatives.length > 0 ? { alternatives } : {}),
+  };
+}
+
+function withSessionBreak(step: WorkflowStep): WorkflowStep {
+  return { ...step, sessionBreakBefore: true };
+}
+
+export function workflowPlan(
+  availableSkills: readonly string[] = [
+    ...PRE_EXPLORE_SKILLS,
+    ...Object.values(SHARED_OPTIONAL_SKILLS),
+  ],
+): WorkflowPlan {
+  const availableSkillSet = new Set(availableSkills);
+  const preExploreAlternatives: WorkflowAlternative[] = [];
+  for (const name of PRE_EXPLORE_SKILLS) {
+    if (!availableSkillSet.has(name)) continue;
+    preExploreAlternatives.push({
+      name,
+      description:
+        name === "mate-interview-me"
+          ? "Difference: guided, one-question-at-a-time clarification. Best when: the request is ambiguous and intent, constraints, or scope still need confirmation."
+          : "Difference: adversarial, round-based review of the full design-tree frontier. Best when: the direction is mostly known but hidden assumptions, risks, and downstream impacts need surfacing.",
+      prompt: `/${name} for ${CHANGE_PLACEHOLDER}`,
+      copyPrompt: `/${name} for`,
+    });
+  }
+  const start = optionalStep(
+    "pre-explore",
+    "pre-explore",
+    "Clarifies intent with confidence and explicit confirmation, or stress-tests the full design frontier before the schema path turns it into artifacts.",
+    "One conversational choice settles uncertainty early without invoking documentation or implementation work.",
+    preExploreAlternatives,
+  );
+
+  const branches: WorkflowBranch[] = [
+    {
+      profile: "mate-v1",
+      label: "mate-v1",
+      description: "Full planning path for changes that need exploration and technical design.",
+      steps: [
+        skillStep(
+          "explore",
+          "explore",
+          "Resolves repository evidence, unknowns, options, and direction.",
+          "It separates uncertainty from the proposal's committed motivation and scope.",
+          "mate-v1",
+        ),
+        skillStep(
+          "proposal",
+          "proposal",
+          "Commits why the change is needed and what is in scope.",
+          "A written scope gives specs, design, and tasks one decision to build from.",
+          "mate-v1",
+        ),
+        reviewStep(
+          "specs",
+          "specs",
+          "Defines the observable behavior the system must provide.",
+          "The delta is the contract that will later be merged into the canonical spec.",
+          "mate-v1",
+        ),
+        reviewStep(
+          "design",
+          "design",
+          "Records the technical decisions for implementing the change.",
+          "Separating how from what exposes risks before implementation starts.",
+          "mate-v1",
+        ),
+        reviewStep(
+          "tasks",
+          "tasks",
+          "Orders the implementation and verification work.",
+          "Small, ordered tasks turn the agreed artifacts into a trackable build path.",
+          "mate-v1",
+        ),
+        withSessionBreak(
+          skillStep(
+            "apply",
+            "apply",
+            "Implements the change by working through the generated tasks.",
+            "Applying only approved tasks keeps code changes inside the agreed scope.",
+            "mate-v1",
+          ),
+        ),
+      ],
+    },
+    {
+      profile: "mate-minimal",
+      label: "mate-minimal",
+      description:
+        "Short path that creates only specs and tasks for one-Area, low-risk changes; switch to mate-v1 when uncertain.",
+      steps: [
+        skillStep(
+          "propose",
+          "propose",
+          "Creates the concise, parser-compatible behavior change.",
+          "OpenSpec generates the minimal specs and tasks artifacts from the agreed direction.",
+          "mate-minimal",
+        ),
+        reviewStep(
+          "specs",
+          "specs",
+          "Defines the behavior change as a concise, parser-compatible user story.",
+          "Reviewing the generated delta confirms the small change before tasks are applied.",
+          "mate-minimal",
+        ),
+        reviewStep(
+          "tasks",
+          "tasks",
+          "Orders the implementation and verification work.",
+          "The checklist keeps a deliberately small change concrete and reviewable.",
+          "mate-minimal",
+        ),
+        withSessionBreak(
+          skillStep(
+            "apply",
+            "apply",
+            "Implements the change by working through the generated tasks.",
+            "Applying only the short approved checklist keeps the low-risk boundary intact.",
+            "mate-minimal",
+          ),
+        ),
+      ],
+    },
+  ];
+
+  const showMe = optionalStep(
+    "show-me",
+    "mate show me",
+    "Shows what the applied change did as a rendered diagram and a colorized diff, delivered as a Mate report.",
+    "Seeing the resulting structure and the actual diff is what tells the reviewer whether cleanup is warranted.",
+  );
+  const simplify = optionalStep(
+    "simplify",
+    "mate simplify code",
+    "Looks for smaller, clearer code once the tests pass, preserving behavior and rerunning the relevant tests.",
+    "Cleanup lands before the specs are archived, so shipped code and recorded specs stay aligned.",
+  );
+  /** Peers, not prerequisites: an unreported skill drops its step and the rest keep their order. */
+  const optionalReview: WorkflowStep[] = [];
+  for (const step of [showMe, simplify]) {
+    if (!availableSkillSet.has(SHARED_OPTIONAL_SKILLS[step.id as SharedOptionalId])) continue;
+    optionalReview.push(optionalReview.length === 0 ? withSessionBreak(step) : step);
+  }
+  const archive = skillStep(
+    "archive",
+    "openspec archive change",
+    "Archives the verified change and its approved artifacts, applying its delta specs to the canonical specs.",
+    "Archiving validates the change, requires it to be complete, and is the precondition publishing refuses without.",
+  );
+  const finishStep = {
+    kind: "completion" as const,
+    id: "finish",
+    title: "mate artifact publish",
+    what: "Presents the already-archived changes and the drifted canonical specs as two selectable tables, then runs `mate artifact publish` for exactly what the developer picks — announcing that each selection is committed, tagged, and pushed to the companion Git repository before the first one runs.",
+    why: "It is the only sanctioned completion; a hand-committed publication leaves the anchor untagged and unrevertable, and a drifted spec shipped under an old archive's tag misfiles today's edit under a change that did not produce it.",
+    badges: ["skill"] as WorkflowStepBadge[],
+  };
+
+  return {
+    start,
+    branches,
+    shared: [...optionalReview, archive],
+    finish: {
+      ...finishStep,
+      prompt: stepPrompt(finishStep),
+      copyPrompt: stepPrompt(finishStep, undefined, false),
+    },
+  };
+}
+
+export function workflowSteps(profile: WorkflowProfile = "mate-v1"): WorkflowStep[] {
+  const plan = workflowPlan();
+  const branch = plan.branches.find((entry) => entry.profile === profile);
+  if (!branch) return [plan.start, ...plan.shared, plan.finish];
+  return [plan.start, ...branch.steps, ...plan.shared, plan.finish];
+}

package/src/cli/commands/studio/views/workflow/transcript.tsx

@@ -0,0 +1,190 @@
+/** @jsxImportSource hono/jsx */
+
+import type { StudioCompanionPayload } from "../../payload";
+import {
+  workflowPlan,
+  type WorkflowBranch,
+  type WorkflowStep,
+  type WorkflowStepBadge,
+} from "./steps";
+
+type WorkflowPlan = ReturnType<typeof workflowPlan>;
+
+export function WorkflowTranscript({ payload }: { payload: StudioCompanionPayload }) {
+  return <CommandTranscript plan={workflowPlan(payload.skills)} />;
+}
+
+function CommandTranscript({ plan }: { plan: WorkflowPlan }) {
+  return (
+    <section className="workflow-console" aria-label="Workflow execution map">
+      <header className="workflow-console-header">
+        <div className="workflow-console-header-title">
+          <span>Workflow map</span>
+          <strong>Companion delivery path</strong>
+        </div>
+        <span>Read-only guide</span>
+      </header>
+      <div className="workflow-console-body">
+        <ConsoleLine step={plan.start} marker="01" />
+        <div className="workflow-console-context">
+          <span>precondition</span>
+          <div>
+            <p>The desired change, its scope, and the risk involved are clear.</p>
+            <small>If any of that is unclear, pre-explore above resolves it first.</small>
+          </div>
+        </div>
+        <div className="workflow-console-schema" data-workflow-schema-root>
+          <div
+            className="workflow-console-tabs"
+            data-workflow-schema-switch
+            role="tablist"
+            aria-label="Planning depth"
+          >
+            {plan.branches.map((branch, index) => (
+              <button
+                key={branch.profile}
+                type="button"
+                role="tab"
+                data-workflow-schema-profile={branch.profile}
+                aria-selected={index === 0}
+              >
+                <strong>{branch.label}</strong>
+                <small>{index === 0 ? "full planning" : "minimal planning"}</small>
+              </button>
+            ))}
+          </div>
+          <div className="workflow-console-panels">
+            {plan.branches.map((branch, branchIndex) => (
+              <section
+                key={branch.profile}
+                data-workflow-schema-panel={branch.profile}
+                data-active={branchIndex === 0 ? "true" : "false"}
+                role="tabpanel"
+              >
+                <div className="workflow-console-branch-rule">
+                  <p className="workflow-console-branch-rule-description">
+                    {planningRule(branch.profile)}
+                  </p>
+                </div>
+                {branch.steps.map((step, index) => (
+                  <div key={step.id}>
+                    {step.sessionBreakBefore ? <WorkflowSessionBreak /> : null}
+                    <ConsoleLine
+                      step={step}
+                      marker={`${branchIndex === 0 ? "F" : "M"}${String(index + 1).padStart(2, "0")}`}
+                    />
+                  </div>
+                ))}
+              </section>
+            ))}
+          </div>
+        </div>
+        <div className="workflow-console-divider">paths rejoin</div>
+        {plan.shared.map((step) => (
+          <div key={step.id}>
+            {step.sessionBreakBefore ? <WorkflowSessionBreak /> : null}
+            <ConsoleLine step={step} marker="+" />
+          </div>
+        ))}
+        <div className="workflow-console-divider">feature is on production</div>
+        <ConsoleLine step={plan.finish} marker="END" />
+      </div>
+    </section>
+  );
+}
+
+function planningRule(profile: WorkflowBranch["profile"]): string {
+  return profile === "mate-v1"
+    ? "Use when intent is clear, but the solution, repository evidence, or risk still needs exploration."
+    : "Use only when intent and scope are clear, the change is low-risk, and it stays within one Area.";
+}
+
+function ConsoleLine({ step, marker }: { step: WorkflowStep; marker: string }) {
+  const hasAlternatives = Boolean(step.alternatives?.length);
+
+  return (
+    <article className="workflow-console-line">
+      <span className="workflow-console-gutter">{marker}</span>
+      <div className="workflow-console-line-body">
+        <div className="workflow-console-step-title">
+          <strong>{step.title}</strong>
+          <WorkflowBadges badges={step.badges} />
+        </div>
+        {!hasAlternatives ? (
+          step.kind === "review" ? (
+            <div className="workflow-console-command workflow-console-review">
+              <span className="workflow-console-command-label">Review</span>
+              <code>{step.prompt}</code>
+            </div>
+          ) : (
+            <div className="workflow-console-command">
+              <span className="workflow-console-command-label">Run</span>
+              <code>{step.prompt}</code>
+              <WorkflowCopy text={step.copyPrompt} label={`${step.title} prompt`} />
+            </div>
+          )
+        ) : null}
+        {hasAlternatives ? <WorkflowOptions step={step} /> : null}
+        <div className="workflow-console-explanation">
+          <div className="workflow-console-detail">
+            <span>What</span>
+            <p>{step.what}</p>
+          </div>
+          <div className="workflow-console-detail">
+            <span>Why</span>
+            <small>{step.why}</small>
+          </div>
+        </div>
+        {!hasAlternatives ? <WorkflowOptions step={step} /> : null}
+      </div>
+    </article>
+  );
+}
+
+function WorkflowOptions({ step }: { step: WorkflowStep }) {
+  if (!step.alternatives?.length) return null;
+  return (
+    <div className="workflow-option-list">
+      {step.alternatives.map((alternative) => (
+        <div key={alternative.name} className="workflow-option">
+          <div className="workflow-console-command">
+            <span className="workflow-console-command-label">Option</span>
+            <code>{alternative.prompt}</code>
+            <WorkflowCopy text={alternative.copyPrompt} label={`${alternative.name} prompt`} />
+          </div>
+          <small>{alternative.description}</small>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function WorkflowCopy({ text, label }: { text: string; label: string }) {
+  return (
+    <button type="button" className="runway-step-copy" data-copy={text} data-copy-label={label}>
+      Copy
+    </button>
+  );
+}
+
+function WorkflowSessionBreak() {
+  return <div className="workflow-session-break">New session / clean chat</div>;
+}
+
+function WorkflowBadges({ badges }: { badges: WorkflowStepBadge[] }) {
+  return (
+    <span className="workflow-badges">
+      {badges.map((badge) => (
+        <em key={badge} className={`runway-step-badge runway-step-badge-${badge}`}>
+          {badgeLabel(badge)}
+        </em>
+      ))}
+    </span>
+  );
+}
+
+function badgeLabel(badge: WorkflowStepBadge): string {
+  if (badge === "human-in-loop") return "Review";
+  if (badge === "openspec") return "OpenSpec";
+  return badge;
+}

package/src/cli/commands/unwrap.ts

@@ -0,0 +1,70 @@
+import { FRAMEWORK_NAME } from "../../framework";
+import { findRepoLocalLinkedRepository } from "../../lib/orchestrator/repo-local-registry";
+import { unwrapWorkingRuntimeDocuments } from "../../lib/orchestrator/working-repo-projection";
+
+export interface UnwrapCommandDependencies {
+  findRepoLocalLinkedRepository?: typeof findRepoLocalLinkedRepository;
+  unwrapWorkingRuntimeDocuments?: typeof unwrapWorkingRuntimeDocuments;
+}
+
+export const unwrapCommandDeps: Required<UnwrapCommandDependencies> = {
+  findRepoLocalLinkedRepository,
+  unwrapWorkingRuntimeDocuments,
+};
+
+/**
+ * Withdraws the runtime documents `mate wrap` placed and nothing else: the
+ * Projection Root, the Repository Link and the companion link all stay, so a
+ * Managed Session resolves exactly as it did before the wrap. That is what
+ * separates this from `mate working cleanup`, which removes Mate's whole local
+ * integration including the link.
+ *
+ * Takes no companion. The manifest at the Projection Root records what was
+ * placed, so unwrapping needs no answer to which companion placed it — which
+ * also means it still works when the companion is gone.
+ */
+export async function runUnwrapCommand(
+  argv: string[] = [],
+  cwd: string = process.cwd(),
+  deps: UnwrapCommandDependencies = {},
+): Promise<void> {
+  const findRepository =
+    deps.findRepoLocalLinkedRepository ?? unwrapCommandDeps.findRepoLocalLinkedRepository;
+  const unwrap =
+    deps.unwrapWorkingRuntimeDocuments ?? unwrapCommandDeps.unwrapWorkingRuntimeDocuments;
+
+  if (argv.length > 0) {
+    console.error(`${FRAMEWORK_NAME}: usage: ${FRAMEWORK_NAME} unwrap`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const repository = await findRepository(cwd);
+  if (!repository) {
+    console.error(
+      `${FRAMEWORK_NAME}: this directory is not a working repository linked to a companion.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = await unwrap(repository.path);
+  if (result.kind === "failed") {
+    console.error(
+      `${FRAMEWORK_NAME}: failed to withdraw ${result.document} for ${repository.id}: ${result.error.message}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.kind === "absent") {
+    console.log(`Not wrapped: ${repository.id}`);
+    return;
+  }
+
+  console.log(`Unwrapped ${repository.id}`);
+  for (const document of result.documents) {
+    console.log(`  Withdrawn: ${document}`);
+  }
+  console.log(`\`${FRAMEWORK_NAME} claude\` and \`${FRAMEWORK_NAME} opencode\` work here again.`);
+}