@selesai/code 0.1.19 → 0.2.1

package/dist/extensions/workflow/modes/prototype.ts

@@ -0,0 +1,156 @@
+import type {
+  Phase,
+  PromptContext,
+  WorkflowConfig,
+  WorkflowModeRegistration,
+} from "../state-machine.ts";
+
+// ponytail: prototype workflow — full 7-phase tool-driven loop:
+// grill → research → plan → reuse → handoff → loop → audit.
+// skipRules + closeArtifacts are wired by the adapter (git reuse-skip is
+// shared by every mode today); this file is pure phase/prompt config.
+
+const phases: Phase[] = [
+  "grilling",
+  "research",
+  "plan",
+  "reuse",
+  "handoff",
+  "loop",
+  "audit",
+];
+
+const prompts: Partial<Record<Phase, (ctx: PromptContext) => string>> = {
+  grilling: ({ artifactDir, userPrompt }) =>
+    `You are in the GRILLING phase of a prototype workflow.
+
+User request:
+${userPrompt}
+
+Use the question tool to grill the user until requirements are unambiguous. Ask focused clarifying questions ONE question tool call at a time. Adapt each follow-up to what the user reveals. Dig into scope, constraints, success criteria, and edge cases. Use your judgement — no fixed checklist.
+
+For each question tool call:
+- Provide a concise question.
+- Pass a short context summary when it depends on prior findings.
+- Prefer options when choices are known. Give each option a clear label and a brief description.
+- Always set allowFreeform=true so the user can type a custom answer.
+- Keep allowMultiple=false unless multiple selections genuinely apply.
+
+Example:
+  question({
+    question: "What should the output format be?",
+    context: "The user wants a report generator. We need to pick the default export format.",
+    options: [
+      { label: "Markdown", description: "Simple, version-control friendly" },
+      { label: "PDF", description: "Polished, shareable document" },
+    ],
+    allowFreeform: true,
+  })
+
+When shared understanding is reached, do NOT write the file yet. Show a concise requirements summary draft and ask exactly: "Approve writing this requirements summary to ${artifactDir}/requirements.md?" Allow "keep grilling" or added details.
+
+Artifact target: ${artifactDir}/requirements.md
+- Name that exact full path in the approval question.
+- Do NOT shorten, translate, censor, sanitize, or invent a different path.
+- Only after explicit approval, call write_workflow_artifact with content only. Do not use write.
+
+The workflow advances once ${artifactDir}/requirements.md exists.`,
+  research: ({ artifactDir }) =>
+    `You are in the RESEARCH phase (optional).
+
+Only research if the task depends on fast-changing external knowledge (libraries, frameworks, languages/SDKs, APIs, or unfamiliar alternatives). Skip what you already know well.
+
+Decide: is research needed?
+- If YES: use web_search_exa or webfetch via bash to gather current, authoritative information, then synthesize actionable findings (versions, APIs, pitfalls, recommended approaches).
+- If NO: skip real research.
+
+Either way, call write_workflow_artifact with research.md content. If skipped, state briefly why. If researched, record findings the plan can rely on.
+
+The workflow advances once ${artifactDir}/research.md exists.`,
+  plan: ({ artifactDir }) =>
+    `You are in the PLAN phase.
+
+Produce the concrete build plan for the actual prototype/output — not a plan for research. Use ${artifactDir}/requirements.md and ${artifactDir}/research.md (if it contains real findings). Cover what to build, how, in what order, which components, and what the finished prototype looks like.
+
+If research was skipped, proceed directly — you already understand the user's intent from grilling.
+
+Spawn the ARCHITECT sub-agent via the subagent tool (subagent_type "architect"). Do NOT pass a model parameter. Craft a tailored prompt from ${artifactDir}/requirements.md and ${artifactDir}/research.md so the architect plans for THIS task. The architect returns the plan; the workflow saves it to ${artifactDir}/plan.md.
+
+The workflow advances once ${artifactDir}/plan.md exists.`,
+  reuse: ({ artifactDir }) =>
+    `You are in the REUSE phase (optional).
+
+Decide whether codebase exploration is useful. Skip if the project is empty, the task creates something wholly new, or there is clearly nothing to reuse.
+
+If unsure, ask the user one focused question: "Should I explore the existing codebase for reusable patterns before implementing?" Then follow their answer.
+
+If YES (or user confirms): spawn the EXPLORER sub-agent via the subagent tool (subagent_type "explorer"). Do NOT pass a model parameter. Craft a specific prompt from ${artifactDir}/requirements.md and ${artifactDir}/plan.md pointing it at relevant areas, patterns, and dependencies (e.g., Tailwind setup, state-machine usage). Synthesize the findings into ${artifactDir}/reuse.md: what is reusable, where, and how to leverage it.
+
+If NO: call write_workflow_artifact with a brief skip note explaining why.
+
+The workflow advances once ${artifactDir}/reuse.md exists.`,
+  handoff: ({ artifactDir }) =>
+    `You are in the HANDOFF phase.
+
+Compile a self-contained handoff document so loop-phase sub-agents understand full project context without re-grilling.
+
+Draw from all prior phases:
+- ${artifactDir}/requirements.md (grilling outcomes)
+- ${artifactDir}/research.md (research, or the skip note)
+- ${artifactDir}/plan.md (the build plan)
+- ${artifactDir}/reuse.md (codebase exploration findings)
+
+Spawn the RECAPPER sub-agent via the subagent tool (subagent_type "recapper"). Do NOT pass a model parameter. Craft a tailored prompt pointing the recapper at all four artifact files and telling it what the prototype is about. The recapper returns the handoff; the workflow saves it to ${artifactDir}/handoff.md.
+
+The workflow advances once ${artifactDir}/handoff.md exists.`,
+  loop: ({ artifactDir }) =>
+    `You are in the LOOP (orchestration) phase. Delegate implementation to sub-agents — do not write code yourself.
+
+Use read to inspect ${artifactDir}/plan.md, ${artifactDir}/handoff.md, ${artifactDir}/research.md, and ${artifactDir}/reuse.md. Using that context, GENERATE YOUR OWN delegation prompts (no static template):
+1. Dispatch ONE builder sub-agent via the subagent tool (subagent_type "builder"). Do NOT pass a model parameter. Give it plan + handoff + any research/reuse context, tailored to this task. Instruct it to implement every task in plan.md in order. All code changes go in the workspace, never in ${artifactDir}.
+2. Dispatch ONE commentator sub-agent via the subagent tool (subagent_type "commentator"). Do NOT pass a model parameter. Review the builder's diff against plan.md. Generate the review prompt YOURSELF based on what matters for this task.
+3. If the commentator reports blocking issues, dispatch the builder again with the issues to fix, then re-run the commentator. Repeat until no issues.
+4. Call write_workflow_artifact with a one-line summary of the finished plan.
+
+Tailor prompts to the task — not generic. The workflow advances to audit once ${artifactDir}/loop-complete.md exists.`,
+  audit: ({ artifactDir }) =>
+    `You are in the AUDIT (review) phase.
+
+Review uncommitted changes for correctness, plan adherence, and over-engineering. Use ponytail-review style: cut bloat, unnecessary abstractions, dead flexibility, and reinvented stdlib/native behavior.
+
+1. Spawn the COMMENTATOR sub-agent via the subagent tool (subagent_type "commentator"). Do NOT pass a model parameter. Craft a tailored prompt from the full uncommitted diff and ${artifactDir}/plan.md. The commentator returns its review; the workflow saves it to ${artifactDir}/review.md.
+2. If ${artifactDir}/review.md lists actionable issues, spawn the BUILDER sub-agent via the subagent tool (subagent_type "builder"). Do NOT pass a model parameter. Instruct it to fix every issue in the workspace, never in ${artifactDir}.
+3. Re-dispatch the commentator until ${artifactDir}/review.md says the review is clean and no issues remain.
+
+The workflow closes once ${artifactDir}/review.md exists and the commentator reports no outstanding issues.`,
+};
+
+const config: WorkflowConfig = {
+  mode: "prototype",
+  phases,
+  phaseArtifacts: {
+    grilling: "requirements.md",
+    research: "research.md",
+    plan: "plan.md",
+    reuse: "reuse.md",
+    handoff: "handoff.md",
+    loop: "loop-complete.md",
+    audit: "review.md",
+  },
+  prompts,
+  closeArtifacts: ["review.md"],
+  statusKey: "prototype",
+  entryType: "prototype-phase",
+  footerLabel: "prototype",
+};
+
+export const prototypeMode: WorkflowModeRegistration = {
+  config,
+  commandName: "prototype",
+  commandDescription:
+    "Run the prototype workflow (grill → research → plan → reuse → handoff → loop → audit)",
+  toolNames: { start: "start_workflow", end: "end_workflow" },
+  toolLabels: { start: "Start Workflow", end: "End Workflow" },
+};
+
+export default prototypeMode;

package/dist/extensions/workflow/modes/quick.ts

@@ -0,0 +1,138 @@
+import type {
+  Phase,
+  PromptContext,
+  WorkflowConfig,
+  WorkflowModeRegistration,
+} from "../state-machine.ts";
+
+// ponytail: quick workflow — same tool-driven loop as prototype, but shorter:
+// grill (max 4 questions) → plan → reuse → handoff → loop → audit.
+// No research phase. skipRules + closeArtifacts wired by the adapter.
+
+const phases: Phase[] = [
+  "grilling",
+  "plan",
+  "reuse",
+  "handoff",
+  "loop",
+  "audit",
+];
+
+const prompts: Partial<Record<Phase, (ctx: PromptContext) => string>> = {
+  grilling: ({ artifactDir, userPrompt }) =>
+    `You are in the GRILLING phase of a QUICK workflow.
+
+User request:
+${userPrompt}
+
+Use the question tool to grill the user. Ask AT MOST 4 focused clarifying questions — ONE question tool call at a time. Adapt each follow-up to prior answers. Dig into scope, constraints, success criteria, and edge cases.
+
+For each question tool call:
+- Provide a concise question.
+- Pass a short context summary when it depends on prior findings.
+- Prefer options when choices are known. Give each option a clear label and a brief description.
+- Always set allowFreeform=true so the user can type a custom answer.
+- Keep allowMultiple=false unless multiple selections genuinely apply.
+
+Example:
+  question({
+    question: "What should the output format be?",
+    context: "The user wants a report generator. We need to pick the default export format.",
+    options: [
+      { label: "Markdown", description: "Simple, version-control friendly" },
+      { label: "PDF", description: "Polished, shareable document" },
+    ],
+    allowFreeform: true,
+  })
+
+When you have enough clarity OR up to 10 questions max (less is better) have been asked, stop grilling. Show a concise requirements summary, then ask exactly: "Approve writing this requirements summary to ${artifactDir}/requirements.md?"
+
+Artifact target: ${artifactDir}/requirements.md
+- Name that exact full path in the approval question.
+- Do NOT shorten, translate, censor, sanitize, or invent a different path.
+- Only after explicit approval, call write_workflow_artifact with content only. Do not use write.
+
+The workflow advances once ${artifactDir}/requirements.md exists.`,
+  plan: ({ artifactDir }) =>
+    `You are in the PLAN phase.
+
+This is a QUICK workflow — no separate research phase. Use ${artifactDir}/requirements.md to produce the concrete build plan: what to build, how, in order, components, and what the finished prototype looks like.
+
+Spawn the ARCHITECT sub-agent via the subagent tool (subagent_type "architect"). Do NOT pass a model parameter. Craft a tailored prompt from ${artifactDir}/requirements.md so the architect plans for THIS task. The architect returns the plan; the workflow saves it to ${artifactDir}/plan.md.
+
+The workflow advances once ${artifactDir}/plan.md exists.`,
+  reuse: ({ artifactDir }) =>
+    `You are in the REUSE phase (optional).
+
+Decide whether codebase exploration is useful. Skip if the project is empty, the task creates something wholly new, or there is clearly nothing to reuse.
+
+If unsure, ask the user one focused question: "Should I explore the existing codebase for reusable patterns before implementing?" Then follow their answer.
+
+If YES (or user confirms): spawn the EXPLORER sub-agent via the subagent tool (subagent_type "explorer"). Do NOT pass a model parameter. Craft a specific prompt from ${artifactDir}/requirements.md and ${artifactDir}/plan.md pointing it at relevant areas, patterns, and dependencies. Synthesize the findings into ${artifactDir}/reuse.md: what is reusable, where, and how to leverage it.
+
+If NO: call write_workflow_artifact with a brief skip note explaining why.
+
+The workflow advances once ${artifactDir}/reuse.md exists.`,
+  handoff: ({ artifactDir }) =>
+    `You are in the HANDOFF phase.
+
+Compile a self-contained handoff document so loop-phase sub-agents understand full project context without re-grilling.
+
+Draw from all prior phases:
+- ${artifactDir}/requirements.md
+- ${artifactDir}/plan.md
+- ${artifactDir}/reuse.md
+
+Spawn the RECAPPER sub-agent via the subagent tool (subagent_type "recapper"). Do NOT pass a model parameter. Craft a tailored prompt pointing the recapper at all three artifact files and telling it what the prototype is about. The recapper returns the handoff; the workflow saves it to ${artifactDir}/handoff.md.
+
+The workflow advances once ${artifactDir}/handoff.md exists.`,
+  loop: ({ artifactDir }) =>
+    `You are in the LOOP (orchestration) phase. Delegate implementation to sub-agents — do not write code yourself.
+
+Use read to inspect ${artifactDir}/plan.md, ${artifactDir}/handoff.md, and ${artifactDir}/reuse.md. Using that context, GENERATE YOUR OWN delegation prompts:
+1. Dispatch ONE builder sub-agent via the subagent tool (subagent_type "builder"). Do NOT pass a model parameter. Give it plan + handoff + reuse context, tailored to this task. Instruct it to implement every task in plan.md in order. All code changes go in the workspace, never in ${artifactDir}.
+2. Dispatch ONE commentator sub-agent via the subagent tool (subagent_type "commentator"). Do NOT pass a model parameter. Review the builder's diff against plan.md. Generate the review prompt YOURSELF.
+3. If the commentator reports blocking issues, dispatch the builder again with the issues to fix, then re-run the commentator. Repeat until no issues.
+4. Call write_workflow_artifact with a one-line summary of the finished plan.
+
+The workflow advances to audit once ${artifactDir}/loop-complete.md exists.`,
+  audit: ({ artifactDir }) =>
+    `You are in the AUDIT (review) phase.
+
+Review uncommitted changes for correctness, plan adherence, and over-engineering. Use ponytail-review style: cut bloat, unnecessary abstractions, dead flexibility, and reinvented stdlib/native behavior.
+
+1. Spawn the COMMENTATOR sub-agent via the subagent tool (subagent_type "commentator"). Do NOT pass a model parameter. Craft a tailored prompt from the full uncommitted diff and ${artifactDir}/plan.md. The commentator returns its review; the workflow saves it to ${artifactDir}/review.md.
+2. If ${artifactDir}/review.md lists actionable issues, spawn the BUILDER sub-agent via the subagent tool (subagent_type "builder"). Do NOT pass a model parameter. Instruct it to fix every issue in the workspace, never in ${artifactDir}.
+3. Re-dispatch the commentator until ${artifactDir}/review.md says the review is clean and no issues remain.
+
+The workflow closes once ${artifactDir}/review.md exists and the commentator reports no outstanding issues.`,
+};
+
+const config: WorkflowConfig = {
+  mode: "quick",
+  phases,
+  phaseArtifacts: {
+    grilling: "requirements.md",
+    plan: "plan.md",
+    reuse: "reuse.md",
+    handoff: "handoff.md",
+    loop: "loop-complete.md",
+    audit: "review.md",
+  },
+  prompts,
+  closeArtifacts: ["review.md"],
+  statusKey: "quick",
+  entryType: "quick-phase",
+  footerLabel: "quick",
+};
+
+export const quickMode: WorkflowModeRegistration = {
+  config,
+  commandName: "quick",
+  commandDescription:
+    "Run the quick workflow (grill → plan → reuse → handoff → loop → audit)",
+  toolNames: { start: "start_quick_workflow", end: "end_quick_workflow" },
+  toolLabels: { start: "Start Quick Workflow", end: "End Quick Workflow" },
+};
+
+export default quickMode;

package/dist/extensions/workflow/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "@selesai/workflow",
+	"version": "0.0.1",
+	"private": true,
+	"description": "Selesai workflow engine + modes (prototype, quick). Loaded as a bundled pi extension package.",
+	"type": "module",
+	"pi": {
+		"extensions": [
+			"./extension.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	}
+}