acpus 0.5.2 → 0.6.0-alpha.0

package/skills/acpus/eval/evaluations.md

@@ -0,0 +1,47 @@
+# Evaluation Scenarios
+
+Use these scenarios to test that the Skill guides agents toward current Acpus behavior.
+
+## Evaluation 1: Author a minimal workflow
+
+**Query**: "Write an Acpus workflow that takes `{ name }`, runs a local task, and returns a greeting."
+
+**Expected behavior**:
+
+- Uses `defineWorkflow` from `acpus/core`.
+- Uses a TypeScript `workflow.ts`.
+- Uses `step("...").task({ run: { input, exec } })`.
+- Does not add `outputSchema` to the task.
+- Suggests `acpus workflow check workflow.ts` before `run`.
+
+## Evaluation 2: Recover a failed run after source fix
+
+**Query**: "My Acpus run failed, I fixed workflow.ts, should I retry it?"
+
+**Expected behavior**:
+
+- Asks to inspect the run first or uses `acpus runs inspect <run-id>` if run id is given.
+- Explains retry reuses the original frozen workflow.
+- Recommends `acpus runs fork <run-id> --workflow workflow.ts` when source changed.
+
+## Evaluation 3: Configure hooks
+
+**Query**: "Add an Acpus hook when an agent node fails."
+
+**Expected behavior**:
+
+- Uses `.acpus/hooks.json`.
+- Produces an event-map JSON file with `node.failed` top-level key.
+- Uses `match.kind` or `match.nodeId` as regex match fields.
+- Mentions hook context arrives on stdin.
+- Recommends `acpus hooks validate`.
+
+## Evaluation 4: Fix expression bug
+
+**Query**: "Why does `if (input.ready)` fail in my workflow build callback?"
+
+**Expected behavior**:
+
+- Explains `input.ready` is an expression token, not runtime boolean.
+- Replaces JavaScript control flow with graph-level `step().if` or expression helpers such as `and`, `eq`, `ifElse`.
+- Mentions `workflow check` catches Expr truthiness misuse.

package/skills/acpus/examples/hooks.example.json

@@ -0,0 +1,17 @@
+{
+  "run.completed": [
+    {
+      "id": "record-completion",
+      "command": "mkdir -p .acpus/.local/hook-samples && cat > .acpus/.local/hook-samples/last-run-completed.json",
+      "timeout": "10s"
+    }
+  ],
+  "node.failed": [
+    {
+      "id": "record-failed-agent",
+      "match": { "kind": "agent" },
+      "command": "mkdir -p .acpus/.local/hook-samples && cat > .acpus/.local/hook-samples/last-agent-failure.json",
+      "timeout": "10s"
+    }
+  ]
+}

package/skills/acpus/examples/workflows/adversarial-review/workflow.ts

@@ -0,0 +1,248 @@
+import { defineWorkflow, z } from "acpus/core";
+import { md, template } from "acpus/expression";
+
+const Verdict = z.enum(["pass", "pass-with-nits", "needs-work", "block"]);
+
+export default defineWorkflow({
+    name: "adversarial-review",
+    inputSchema: z.object({
+        subject: z.string().describe(
+            "The proposal, design, code change, workflow, plan, or decision to review adversarially.",
+        ),
+        rubric: z.string().describe(
+            "The review standard: what good looks like, what must be true, and which qualities matter most.",
+        ),
+        criteria: z.string().default("").describe(
+            "Optional comma-separated or natural-language review criteria, for example: correctness, DX, runtime safety.",
+        ),
+        context: z.string().default("").describe(
+            "Optional background the agents should consider, such as constraints, prior decisions, known risks, or local workspace context.",
+        ),
+        maxLenses: z.number().default(4).describe(
+            "Maximum number of distinct adversarial review lenses to create.",
+        ),
+    }),
+    agents: {
+        planner: {
+            use: "pi",
+        },
+        reviewer: {
+            use: "pi",
+        },
+        critic: {
+            use: "claude",
+        },
+        synthesizer: {
+            use: "claude",
+        },
+    },
+}).build(({ input, agents, meta, step }) => {
+    const plan = step("plan_lenses").agent({
+        outputSchema: z.object({
+            lenses: z.array(z.object({
+                id: z.string(),
+                prompt: z.string(),
+            })),
+        }),
+        run: {
+            agent: agents.planner,
+            cwd: meta.workspaceDir,
+            prompt: md`
+                You are planning a dynamic adversarial review.
+
+                Subject:
+                ${input.subject}
+
+                Context:
+                ${input.context}
+
+                Rubric:
+                ${input.rubric}
+
+                Criteria:
+                ${input.criteria}
+
+                Maximum lenses:
+                ${input.maxLenses}
+
+                Create the smallest useful set of review lenses.
+
+                Rules:
+                - Use only the subject, context, rubric, criteria, and readable local workspace context.
+                - Prefer 3-5 lenses, but never exceed the maximum.
+                - Avoid duplicate lenses.
+                - Each lens must represent a distinct way the subject could fail.
+                - Each lens id must be short, lowercase, and stable enough for a run key.
+                - Each lens prompt must be a complete natural-language reviewer role, including focus and attack style.
+                - Good lenses include correctness, feasibility, risk, edge cases, rubric compliance, maintainability, authoring fit, runtime contract, testing, migration risk, and DX.`,
+        },
+        timeout: "15m",
+    });
+
+    const reviews = step("blind_reviews").fanout({
+        over: plan.output.lenses,
+        maxConcurrency: 4,
+        key: ({ item }) => template`review-${item.id}`,
+        do: ({ item, step }) => {
+            const review = step("blind_review").agent({
+                run: {
+                    agent: agents.reviewer,
+                    cwd: meta.workspaceDir,
+                    prompt: md`
+                        You are a blind reviewer.
+
+                        Your lens:
+                        ${item.prompt}
+
+                        Subject:
+                        ${input.subject}
+
+                        Context:
+                        ${input.context}
+
+                        Rubric:
+                        ${input.rubric}
+
+                        Criteria:
+                        ${input.criteria}
+
+                        Rules:
+                        - Work independently.
+                        - Do not assume what other reviewers will say.
+                        - Judge only from the given subject, context, rubric, criteria, and readable local workspace context.
+                        - Be adversarial but fair.
+                        - Prefer concrete issues over broad complaints.
+                        - Mark uncertainty explicitly.
+                        - Do not block on nits.
+                        - Do not try to match a JSON schema.
+
+                        Return Markdown with these sections:
+                        - Summary
+                        - Strengths
+                        - Issues
+                        - Hidden assumptions
+                        - Verdict`,
+                },
+                timeout: "30m",
+            });
+
+            return {
+                review: review.output,
+            };
+        },
+    });
+
+    const critiques = step("cross_critiques").fanout({
+        over: plan.output.lenses,
+        maxConcurrency: 4,
+        key: ({ item }) => template`critique-${item.id}`,
+        do: ({ item, step }) => {
+            const critique = step("critique_reviews").agent({
+                run: {
+                    agent: agents.critic,
+                    cwd: meta.workspaceDir,
+                    prompt: md`
+                        You are now a red-team critic.
+
+                        Your lens:
+                        ${item.prompt}
+
+                        Subject:
+                        ${input.subject}
+
+                        Rubric:
+                        ${input.rubric}
+
+                        Criteria:
+                        ${input.criteria}
+
+                        Blind reviews:
+                        ${reviews.output}
+
+                        Attack the reviews, not the author.
+
+                        Look for:
+                        - Unsupported claims.
+                        - Missed risks.
+                        - Overconfidence.
+                        - Contradictions.
+                        - Rubric gaps.
+                        - Recommendations that do not follow from the issue.
+                        - Issues that are mislabeled as blocking or under-labeled as minor.
+
+                        Rules:
+                        - Do not merely summarize.
+                        - Concede points that are already strong.
+                        - Return only substantial objections.
+                        - Do not try to match a JSON schema.
+
+                        Return Markdown with these sections:
+                        - Objections
+                        - Contradictions
+                        - Concessions
+                        - Stronger alternatives`,
+                },
+                timeout: "30m",
+            });
+
+            return {
+                critique: critique.output,
+            };
+        },
+    });
+
+    const synthesis = step("synthesize_result").agent({
+        outputSchema: z.object({
+            verdict: Verdict,
+            report: z.string(),
+        }),
+        run: {
+            agent: agents.synthesizer,
+            cwd: meta.workspaceDir,
+            prompt: md`
+                You are the judge for a dynamic adversarial review.
+
+                Subject:
+                ${input.subject}
+
+                Context:
+                ${input.context}
+
+                Rubric:
+                ${input.rubric}
+
+                Criteria:
+                ${input.criteria}
+
+                Lens plan:
+                ${plan.output}
+
+                Blind reviews:
+                ${reviews.output}
+
+                Cross critiques:
+                ${critiques.output}
+
+                Rules:
+                - Do not average opinions mechanically.
+                - Weigh concrete basis over reviewer confidence.
+                - In the report, separate consensus from unresolved disagreement.
+                - Blocking issues must be explicit.
+                - Nits must not block approval.
+                - Required actions must be concrete and actionable.
+                - Nice-to-have items must not be mixed into required actions.
+                - If the context is insufficient, say so directly instead of inventing evidence.
+                - Do not search the internet.
+                - The report should be natural-language Markdown containing: assessment, consensus, blocking issues, non-blocking issues, unresolved disagreements, required actions, and nice-to-have items.
+                - Return JSON matching the schema.`,
+        },
+        timeout: "30m",
+    });
+
+    return {
+        plan: plan.output,
+        reviews: reviews.output,
+        critiques: critiques.output,
+        synthesis: synthesis.output,
+    };
+});

package/skills/acpus/examples/workflows/change-approval/workflow.ts

@@ -0,0 +1,121 @@
+import { defineWorkflow, z } from "acpus/core";
+import { md, template } from "acpus/expression";
+
+const PlanOut = z.object({
+  ready: z.boolean(),
+  summary: z.string(),
+  nextDraft: z.string(),
+});
+
+export default defineWorkflow({
+  name: "change-approval",
+  description: "Draft and refine an implementation plan, then optionally wait for human approval.",
+  inputSchema: z.object({
+    repoPath: z.path().describe("Repository path where the planning agent should inspect context."),
+    request: z.string().describe("The implementation request or change proposal to turn into a plan."),
+    requireApproval: z.boolean().default(true).describe(
+      "Whether to pause for a human approval signal before the workflow can complete.",
+    ),
+  }),
+  agents: {
+    planner: { use: "codex" },
+  },
+}).build(({ input, agents, meta, step }) => {
+  const initial = step("draft_plan").agent({
+    outputSchema: PlanOut,
+    run: {
+      agent: agents.planner,
+      cwd: input.repoPath,
+      prompt: template`Draft an implementation plan for: ${input.request}`,
+    },
+    retry: { max: 1 },
+    timeout: "20m",
+  });
+
+  const refined = step("refine_plan").loop({
+    initial: {
+      ready: initial.output.ready,
+      round: 0,
+      summary: initial.output.summary,
+      draft: initial.output.nextDraft,
+    },
+    maxIterations: 2,
+    do: ({ iter, previous, step }) => {
+      const review = step("refine_round").agent({
+        outputSchema: PlanOut,
+        run: {
+          agent: agents.planner,
+          cwd: input.repoPath,
+          prompt: md`
+            Refine implementation plan round ${iter}.
+
+            Original request: ${input.request}
+            Previous draft: ${previous.draft}
+            Previous summary: ${previous.summary}
+
+            Return a ready flag, concise summary, and next draft.
+          `,
+        },
+        retry: { max: 1 },
+        timeout: "20m",
+      });
+      return {
+        ready: review.output.ready,
+        round: iter,
+        summary: review.output.summary,
+        draft: review.output.nextDraft,
+      };
+    },
+    stopWhen: ({ result }) => result.ready,
+    onExhausted: "returnLast",
+  });
+
+  const approval = step("approval").if({
+    condition: input.requireApproval,
+    then: ({ step }) => {
+      const human = step("human_approval").signal({
+        outputSchema: z.object({
+          approved: z.boolean(),
+          notes: z.string().default(""),
+        }),
+        run: {
+          prompt: md`
+            Approve the implementation plan for run ${meta.runId}.
+
+            Request: ${input.request}
+            Plan: ${refined.output.draft}
+          `,
+        },
+        timeout: "24h",
+        onTimeout: { action: "fail", message: "approval timed out" },
+      });
+      return { approved: human.output.approved, notes: human.output.notes };
+    },
+    else: ({ step }) => {
+      const automatic = step("auto_approval").task({
+        run: {
+          input: { ready: refined.output.ready },
+          exec: async ({ input }) => ({
+            approved: input.ready,
+            notes: input.ready ? "auto-approved ready plan" : "plan not ready",
+          }),
+        },
+      });
+      return { approved: automatic.output.approved, notes: automatic.output.notes };
+    },
+  });
+
+  step("require_approval").assert({
+    condition: approval.output.approved,
+    message: template`Change approval failed: ${approval.output.notes}`,
+  });
+
+  return {
+    runId: meta.runId,
+    approved: approval.output.approved,
+    notes: approval.output.notes,
+    ready: refined.output.ready,
+    summary: refined.output.summary,
+    plan: refined.output.draft,
+  };
+});

package/skills/acpus/examples/workflows/issue-triage/tasks.ts

@@ -0,0 +1,14 @@
+import { task, z } from "acpus/core";
+
+export const summarizeIssue = task.define({
+  // Reusable task modules may import third-party dependencies installed with the workflow package.
+  inputSchema: z.object({
+    id: z.string(),
+    title: z.string(),
+    labels: z.array(z.string()),
+  }),
+  exec: async ({ input }) => ({
+    labelCount: input.labels.length,
+    titleLine: `${input.id}: ${input.title}`,
+  }),
+});

package/skills/acpus/examples/workflows/issue-triage/workflow.ts

@@ -0,0 +1,146 @@
+import { defineWorkflow, z } from "acpus/core";
+import { eq, md, template } from "acpus/expression";
+import { summarizeIssue } from "./tasks.js";
+
+export default defineWorkflow({
+  name: "issue-triage",
+  description: "Triage repository issues with metadata summarization, agent review, and routing decisions.",
+  inputSchema: z.object({
+    issues: z.array(z.object({
+      id: z.string().describe("Stable issue identifier used for fanout keys and route messages."),
+      title: z.string().describe("Issue title to show the triage agent and queue actions."),
+      body: z.string().describe("Issue body or description to triage."),
+      labels: z.array(z.string()).default([]).describe("Optional issue labels available to metadata and triage steps."),
+    })).describe("Issues to triage in parallel."),
+    repoPath: z.path().describe("Repository path where the triage agent should inspect context."),
+  }),
+  agents: {
+    triager: { use: "codex" },
+  },
+}).build(({ input, agents, meta, step }) => {
+  const triaged = step("triage_issues").fanout({
+    over: input.issues,
+    key: ({ item }) => template`issue-${item.id}`,
+    maxConcurrency: 3,
+    do: ({ item, step }) => {
+      const lane = step("triage_lane").parallel({
+        branches: {
+          metadata: {
+            do: ({ step }) => {
+              const metadata = step("summarize_issue").task({
+                run: {
+                  task: summarizeIssue,
+                  input: { id: item.id, title: item.title, labels: item.labels },
+                  cwd: input.repoPath,
+                },
+              });
+              return {
+                labelCount: metadata.output.labelCount,
+                titleLine: metadata.output.titleLine,
+              };
+            },
+          },
+          review: {
+            do: ({ step }) => {
+              const review = step("review_issue").agent({
+                outputSchema: z.object({
+                  route: z.enum(["now", "later", "escalate"]),
+                  priority: z.number(),
+                  summary: z.string(),
+                }),
+                run: {
+                  agent: agents.triager,
+                  cwd: input.repoPath,
+                  prompt: md`
+                    Triage this issue for the current repository.
+
+                    ID: ${item.id}
+                    Title: ${item.title}
+                    Body: ${item.body}
+                    Labels: ${item.labels}
+
+                    Choose route "now", "later", or "escalate".
+                  `,
+                },
+                timeout: "20m",
+              });
+              return {
+                route: review.output.route,
+                priority: review.output.priority,
+                summary: review.output.summary,
+              };
+            },
+          },
+        },
+      });
+
+      const routed = step("route_issue").switch({
+        cases: [
+          {
+            when: eq(lane.output.review.route, "escalate"),
+            then: ({ step }) => {
+              const escalation = step("prepare_escalation").task({
+                run: {
+                  input: {
+                    id: item.id,
+                    priority: lane.output.review.priority,
+                    summary: lane.output.review.summary,
+                  },
+                  exec: async ({ input }) => ({
+                    owner: "maintainer",
+                    action: `Escalate ${input.id} with priority ${input.priority}: ${input.summary}`,
+                  }),
+                },
+              });
+              return {
+                owner: escalation.output.owner,
+                action: escalation.output.action,
+              };
+            },
+          },
+          {
+            when: eq(lane.output.review.route, "now"),
+            then: ({ step }) => {
+              const queue = step("queue_now").task({
+                run: {
+                  input: { id: item.id, title: lane.output.metadata.titleLine },
+                  exec: async ({ input }) => ({
+                    owner: "oncall",
+                    action: `Queue ${input.title} for this sprint`,
+                  }),
+                },
+              });
+              return { owner: queue.output.owner, action: queue.output.action };
+            },
+          },
+        ],
+        default: ({ step }) => {
+          const backlog = step("backlog_later").task({
+            run: {
+              input: { id: item.id, labelCount: lane.output.metadata.labelCount },
+              exec: async ({ input }) => ({
+                owner: "backlog",
+                action: `Backlog ${input.id} with ${input.labelCount} labels`,
+              }),
+            },
+          });
+          return { owner: backlog.output.owner, action: backlog.output.action };
+        },
+      });
+
+      return {
+        id: item.id,
+        route: lane.output.review.route,
+        priority: lane.output.review.priority,
+        owner: routed.output.owner,
+        action: routed.output.action,
+        summary: lane.output.review.summary,
+      };
+    },
+  });
+
+  return {
+    runId: meta.runId,
+    triaged: triaged.output,
+  };
+});