cool-workflow 0.1.78

package/apps/architecture-review/app.json

@@ -0,0 +1,51 @@
+{
+  "schemaVersion": 1,
+  "id": "architecture-review",
+  "title": "Architecture Review",
+  "summary": "Map a repository architecture, assess risks, verify important findings, and synthesize an evidence-backed verdict.",
+  "version": "0.1.78",
+  "author": "COOLWHITE LLC",
+  "inputs": [
+    {
+      "name": "repo",
+      "type": "path",
+      "required": true,
+      "description": "Repository path to inspect."
+    },
+    {
+      "name": "question",
+      "type": "string",
+      "required": true,
+      "description": "Architecture question or decision to review."
+    },
+    {
+      "name": "invariant",
+      "type": "string",
+      "repeated": true,
+      "description": "Invariant that must remain true."
+    },
+    {
+      "name": "focus",
+      "type": "string",
+      "description": "Optional subsystem, risk area, or file path to emphasize.",
+      "default": "the overall architecture"
+    }
+  ],
+  "sandboxProfiles": [
+    "readonly"
+  ],
+  "compatibility": {
+    "minVersion": "0.1.30",
+    "workflowSchemaVersion": 1,
+    "notes": "Canonical v0.1.30 app migrated from the legacy architecture-review workflow."
+  },
+  "metadata": {
+    "canonical": true,
+    "domain": "software-architecture",
+    "legacyCompatibilityId": "legacy-architecture-review",
+    "maintainedAs": "official-userland"
+  },
+  "workflow": {
+    "entrypoint": "workflow.js"
+  }
+}

package/apps/architecture-review/workflow.js

@@ -0,0 +1,116 @@
+module.exports = ({ workflow, phase, agent, artifact, input }) => {
+  const inputs = [
+    input("repo", {
+      type: "path",
+      required: true,
+      description: "Repository path to inspect."
+    }),
+    input("question", {
+      type: "string",
+      required: true,
+      description: "Architecture question or decision to review."
+    }),
+    input("invariant", {
+      type: "string",
+      repeated: true,
+      description: "Invariant that must remain true."
+    }),
+    input("focus", {
+      type: "string",
+      description: "Optional subsystem, risk area, or file path to emphasize.",
+      default: "the overall architecture"
+    })
+  ];
+
+  return workflow({
+    id: "architecture-review",
+    title: "Architecture Review",
+    summary: "Map a repository architecture, assess risks, verify important findings, and synthesize an evidence-backed verdict.",
+    limits: {
+      maxAgents: 40,
+      maxConcurrentAgents: 6
+    },
+    inputs,
+    sandboxProfiles: ["readonly"],
+    phases: [
+      phase("Map", [
+        agent(
+          "map:server-api",
+          "Map server/API entrypoints, request flows, service boundaries, auth surfaces, and owned state in {{repo}} for {{question}}. Focus: {{focus}}. Invariants: {{invariant}}. Return inspected files, dependencies, invariants, and candidate risks.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "map:web-client",
+          "Map web/client/UI boundaries, local state, backend dependencies, build/runtime assumptions, and candidate risks in {{repo}}. Focus: {{focus}}. Return exact files and commands that informed the map.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "map:db-security",
+          "Map database, persistence, migrations, secrets, auth, permissions, and security-sensitive paths in {{repo}}. Return candidate risks with file paths, config names, and uncertainty boundaries.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "map:deploy-config",
+          "Map deployment, CI, package scripts, Docker or compose files, reverse proxies, environment config, supervision, and operational assumptions. Return concrete files and release or runtime risks.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "map:jobs-operators",
+          "Map background jobs, admin/operator surfaces, queues, scheduled work, generated files, state transitions, and failure recovery paths. Identify missing or non-applicable areas explicitly.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "map:transport-core",
+          "Map protocol, daemon, transport, rendering, networking, worker isolation, or core engine boundaries when present. If absent, explain why with inspected evidence.",
+          { sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Assess", [
+        agent(
+          "assess:security",
+          "Assess mapper findings through a security lens. Separate real, conditional, non-issue, and unknown risks with evidence, falsifiers, and exact files or config keys.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "assess:data-correctness",
+          "Assess data correctness, schema drift, persistence invariants, concurrency, transactions, cache behavior, and state corruption risks. Tie every important claim to inspected evidence.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "assess:failure-modes",
+          "Assess startup, shutdown, retries, partial failure, dependency outage, backup/restore, release rollback, and recovery behavior. Identify deterministic commands that could verify the claims.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "assess:scale-ops",
+          "Assess scale, operational complexity, observability, configuration, packaging, deployment, and maintenance risks. Include exact files, scripts, or missing controls.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "assess:maintainability",
+          "Assess module boundaries, ownership clarity, coupling, extensibility, testability, and future change risk. Distinguish architectural risks from style preferences.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "assess:domain",
+          "Assess domain-specific risks implied by {{question}}, {{focus}}, and the invariants {{invariant}}. Include abuse, misuse, or compatibility concerns only when supported by repository evidence.",
+          { sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Verify", [
+        agent(
+          "verify:p0-p2-risks",
+          "Re-open evidence for every candidate P0/P1/P2 risk. Confirm real risks, downgrade unsupported concerns, and list exact file paths, commands, logs, or unknowns. The cw:result evidence array must cite durable locators.",
+          { requiresEvidence: true, sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Verdict", [
+        artifact(
+          "verdict:synthesis",
+          "Synthesize the architecture verdict for {{question}}: short answer, architecture map, ranked risks, non-issues, recommended changes, and evidence links. The cw:result evidence array must support the final verdict.",
+          { requiresEvidence: true, sandboxProfileId: "readonly" }
+        )
+      ])
+    ]
+  });
+};

package/apps/end-to-end-golden-path/app.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 1,
+  "id": "end-to-end-golden-path",
+  "title": "End-to-End Golden Path",
+  "summary": "Deterministic one-worker workflow app for proving the CW integration chain.",
+  "version": "0.1.78",
+  "author": "COOLWHITE LLC",
+  "inputs": [
+    {
+      "name": "question",
+      "type": "string",
+      "required": true,
+      "description": "Golden path assertion or release question to prove."
+    }
+  ],
+  "sandboxProfiles": [
+    "readonly"
+  ],
+  "compatibility": {
+    "minVersion": "0.1.9",
+    "notes": "Uses the v0.1.9 Workflow App framework contract."
+  },
+  "metadata": {
+    "releaseDiscipline": true,
+    "goldenPath": true
+  },
+  "workflow": {
+    "entrypoint": "workflow.js"
+  }
+}

package/apps/end-to-end-golden-path/workflow.js

@@ -0,0 +1,33 @@
+module.exports = ({ workflow, phase, agent, input }) => {
+  const inputs = [
+    input("question", {
+      type: "string",
+      required: true,
+      description: "Golden path assertion or release question to prove."
+    })
+  ];
+
+  return workflow({
+    id: "end-to-end-golden-path",
+    title: "End-to-End Golden Path",
+    summary: "Deterministic one-worker workflow app for proving the CW integration chain.",
+    limits: {
+      maxAgents: 1,
+      maxConcurrentAgents: 1
+    },
+    inputs,
+    sandboxProfiles: ["readonly"],
+    phases: [
+      phase("Golden Path", [
+        agent(
+          "golden:path",
+          [
+            "Prove the CW end-to-end golden path for {{question}}.",
+            "Return a concise result with a cw:result block and durable file:line evidence."
+          ].join(" "),
+          { requiresEvidence: true, sandboxProfileId: "readonly" }
+        )
+      ])
+    ]
+  });
+};

package/apps/pr-review-fix-ci/app.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": 1,
+  "id": "pr-review-fix-ci",
+  "title": "PR Review Fix CI",
+  "summary": "Review a pull request or branch, inspect CI failures, diagnose actionable issues, optionally patch, verify, and summarize with evidence.",
+  "version": "0.1.78",
+  "author": "COOLWHITE LLC",
+  "inputs": [
+    {
+      "name": "repo",
+      "type": "path",
+      "required": true,
+      "description": "Repository path to inspect."
+    },
+    {
+      "name": "pr",
+      "type": "string",
+      "description": "Pull request number or URL."
+    },
+    {
+      "name": "branch",
+      "type": "string",
+      "description": "Branch to review when no pull request is supplied."
+    },
+    {
+      "name": "base",
+      "type": "string",
+      "description": "Base branch or ref for comparison."
+    },
+    {
+      "name": "ci",
+      "type": "string",
+      "description": "CI system, check name, or log path to inspect."
+    },
+    {
+      "name": "mode",
+      "type": "string",
+      "description": "review for findings only, or fix when file edits are allowed."
+    }
+  ],
+  "sandboxProfiles": [
+    "readonly",
+    "workspace-write"
+  ],
+  "compatibility": {
+    "minVersion": "0.1.30",
+    "workflowSchemaVersion": 1,
+    "notes": "Canonical v0.1.30 app for PR review, CI diagnosis, and optional patch work."
+  },
+  "metadata": {
+    "canonical": true,
+    "domain": "code-review-ci",
+    "mutatesWorkspaceInMode": "fix",
+    "maintainedAs": "official-userland"
+  },
+  "workflow": {
+    "entrypoint": "workflow.js"
+  }
+}

package/apps/pr-review-fix-ci/workflow.js

@@ -0,0 +1,90 @@
+module.exports = ({ workflow, phase, agent, artifact, input }) => {
+  const inputs = [
+    input("repo", {
+      type: "path",
+      required: true,
+      description: "Repository path to inspect."
+    }),
+    input("pr", {
+      type: "string",
+      description: "Pull request number or URL."
+    }),
+    input("branch", {
+      type: "string",
+      description: "Branch to review when no pull request is supplied."
+    }),
+    input("base", {
+      type: "string",
+      description: "Base branch or ref for comparison."
+    }),
+    input("ci", {
+      type: "string",
+      description: "CI system, check name, or log path to inspect."
+    }),
+    input("mode", {
+      type: "string",
+      description: "review for findings only, or fix when file edits are allowed."
+    })
+  ];
+
+  return workflow({
+    id: "pr-review-fix-ci",
+    title: "PR Review Fix CI",
+    summary: "Review a pull request or branch, inspect CI failures, diagnose actionable issues, optionally patch, verify, and summarize with evidence.",
+    limits: {
+      maxAgents: 12,
+      maxConcurrentAgents: 4
+    },
+    inputs,
+    sandboxProfiles: ["readonly", "workspace-write"],
+    phases: [
+      phase("Inspect PR", [
+        agent(
+          "inspect:change-scope",
+          "Inspect {{repo}} for PR {{pr}} or branch {{branch}} against base {{base}}. Identify changed files, touched contracts, generated files, and reviewer-relevant context. Evidence should be exact file paths, refs, diffs, or commands.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "inspect:review-surface",
+          "Review changed behavior for correctness, regressions, missing tests, compatibility, security, and maintenance risk. Return only actionable findings with precise file paths and line-oriented evidence when available.",
+          { sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Inspect CI", [
+        agent(
+          "inspect:ci-failures",
+          "Inspect CI context {{ci}} for failing checks, logs, commands, flakes, skipped jobs, and local reproduction hints. Cite exact check names, command lines, log excerpts, or artifact paths as evidence.",
+          { sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Diagnose", [
+        agent(
+          "diagnose:root-causes",
+          "Diagnose the highest-value PR and CI issues. Classify each as real, conditional, non-issue, or unknown; include reproduction commands, file paths, logs, check names, and falsifiers. The cw:result evidence array must support P0/P1/P2 findings.",
+          { requiresEvidence: true, sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Fix Plan or Patch", [
+        agent(
+          "patch:review-or-fix",
+          "Mode is {{mode}}. In review mode, produce a minimal fix plan without editing files. In fix mode, implement the smallest coherent patch, avoid unrelated refactors, and report changed files, commands run, and risks. Workspace writes are allowed only for this task.",
+          { sandboxProfileId: "workspace-write" }
+        )
+      ]),
+      phase("Verify", [
+        agent(
+          "verify:outcomes",
+          "Verify review conclusions or patches with deterministic commands. Include exact commands, exit status, failing check names, logs, changed files, and unresolved risks. The cw:result evidence array must cite durable local evidence.",
+          { requiresEvidence: true, sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Summary", [
+        artifact(
+          "summary:review",
+          "Write the final PR review and CI summary: blocking findings first, fixes made or proposed, verification evidence, residual risk, and next commands. The cw:result evidence array must support the summary.",
+          { requiresEvidence: true, sandboxProfileId: "readonly" }
+        )
+      ])
+    ]
+  });
+};

package/apps/release-cut/app.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 1,
+  "id": "release-cut",
+  "title": "Release Cut",
+  "summary": "Prepare a release with checklist discipline: version checks, changelog, tests, packaging, release notes, and final verification.",
+  "version": "0.1.78",
+  "author": "COOLWHITE LLC",
+  "inputs": [
+    {
+      "name": "repo",
+      "type": "path",
+      "required": true,
+      "description": "Repository path to prepare."
+    },
+    {
+      "name": "version",
+      "type": "string",
+      "required": true,
+      "description": "Release version to prepare."
+    },
+    {
+      "name": "previousVersion",
+      "type": "string",
+      "description": "Previous released version for changelog comparison."
+    },
+    {
+      "name": "releaseBranch",
+      "type": "string",
+      "description": "Release branch or target ref."
+    },
+    {
+      "name": "dryRun",
+      "type": "boolean",
+      "description": "When true, report intended release actions without publishing."
+    }
+  ],
+  "sandboxProfiles": [
+    "readonly",
+    "workspace-write"
+  ],
+  "compatibility": {
+    "minVersion": "0.1.30",
+    "workflowSchemaVersion": 1,
+    "notes": "Canonical v0.1.30 release preparation app."
+  },
+  "metadata": {
+    "canonical": true,
+    "domain": "release-engineering",
+    "maintainedAs": "official-userland"
+  },
+  "workflow": {
+    "entrypoint": "workflow.js"
+  }
+}

package/apps/release-cut/workflow.js

@@ -0,0 +1,82 @@
+module.exports = ({ workflow, phase, agent, artifact, input }) => {
+  const inputs = [
+    input("repo", {
+      type: "path",
+      required: true,
+      description: "Repository path to prepare."
+    }),
+    input("version", {
+      type: "string",
+      required: true,
+      description: "Release version to prepare."
+    }),
+    input("previousVersion", {
+      type: "string",
+      description: "Previous released version for changelog comparison."
+    }),
+    input("releaseBranch", {
+      type: "string",
+      description: "Release branch or target ref."
+    }),
+    input("dryRun", {
+      type: "boolean",
+      description: "When true, report intended release actions without publishing."
+    })
+  ];
+
+  return workflow({
+    id: "release-cut",
+    title: "Release Cut",
+    summary: "Prepare a release with checklist discipline: version checks, changelog, tests, packaging, release notes, and final verification.",
+    limits: {
+      maxAgents: 12,
+      maxConcurrentAgents: 4
+    },
+    inputs,
+    sandboxProfiles: ["readonly", "workspace-write"],
+    phases: [
+      phase("Preflight", [
+        agent(
+          "preflight:repo-state",
+          "Inspect {{repo}} for release {{version}} on branch {{releaseBranch}}. Report git state, dependency state, required tools, dirty files, generated artifacts, and dryRun={{dryRun}} constraints with exact commands and paths.",
+          { sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Version Audit", [
+        agent(
+          "audit:versions",
+          "Audit all release metadata for target version {{version}} and previous version {{previousVersion}}. Check package manifests, plugin manifests, generated files, docs, changelog, and manually reported versions. Return exact file paths and mismatches.",
+          { sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Changelog and Notes", [
+        agent(
+          "notes:update",
+          "Prepare changelog and release notes for {{version}}. In dryRun={{dryRun}}, report the exact edits that would be made; otherwise update only release documentation and metadata files needed for the release.",
+          { sandboxProfileId: "workspace-write" }
+        )
+      ]),
+      phase("Package", [
+        agent(
+          "package:artifacts",
+          "Prepare release package artifacts for {{version}} using deterministic commands only. In dryRun={{dryRun}}, do not publish; report artifact paths, generated files, checksums when available, and packaging commands.",
+          { sandboxProfileId: "workspace-write" }
+        )
+      ]),
+      phase("Verify", [
+        agent(
+          "verify:package",
+          "Verify release package readiness with deterministic commands, test results, generated dist files, artifact paths, and release metadata. The cw:result evidence array must cite package artifacts, commands, or file locators.",
+          { requiresEvidence: true, sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Release Verdict", [
+        artifact(
+          "verdict:release",
+          "Write the release verdict for {{version}}: ship or hold, checklist status, artifacts, tests, release notes, dry-run limitations, and residual risks. The cw:result evidence array must support the final verdict.",
+          { requiresEvidence: true, sandboxProfileId: "readonly" }
+        )
+      ])
+    ]
+  });
+};

package/apps/research-synthesis/app.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": 1,
+  "id": "research-synthesis",
+  "title": "Research Synthesis",
+  "summary": "Split a research question into claims, investigate sources, cross-check evidence, verify claims, and synthesize a concise answer.",
+  "version": "0.1.78",
+  "author": "COOLWHITE LLC",
+  "inputs": [
+    {
+      "name": "question",
+      "type": "string",
+      "required": true,
+      "description": "Research question to answer."
+    },
+    {
+      "name": "source",
+      "type": "string",
+      "repeated": true,
+      "description": "Preferred primary or official source, URL, citation, or local file."
+    },
+    {
+      "name": "scope",
+      "type": "string",
+      "description": "Optional boundary for the synthesis."
+    },
+    {
+      "name": "freshness",
+      "type": "string",
+      "description": "Optional freshness requirement or as-of date."
+    }
+  ],
+  "sandboxProfiles": [
+    "readonly",
+    "locked-down"
+  ],
+  "compatibility": {
+    "minVersion": "0.1.30",
+    "workflowSchemaVersion": 1,
+    "notes": "Canonical v0.1.30 app migrated from the legacy research-synthesis workflow."
+  },
+  "metadata": {
+    "canonical": true,
+    "domain": "research",
+    "legacyCompatibilityId": "legacy-research-synthesis",
+    "maintainedAs": "official-userland"
+  },
+  "workflow": {
+    "entrypoint": "workflow.js"
+  }
+}

package/apps/research-synthesis/workflow.js

@@ -0,0 +1,76 @@
+module.exports = ({ workflow, phase, agent, artifact, input }) => {
+  const inputs = [
+    input("question", {
+      type: "string",
+      required: true,
+      description: "Research question to answer."
+    }),
+    input("source", {
+      type: "string",
+      repeated: true,
+      description: "Preferred primary or official source, URL, citation, or local file."
+    }),
+    input("scope", {
+      type: "string",
+      description: "Optional boundary for the synthesis."
+    }),
+    input("freshness", {
+      type: "string",
+      description: "Optional freshness requirement or as-of date."
+    })
+  ];
+
+  return workflow({
+    id: "research-synthesis",
+    title: "Research Synthesis",
+    summary: "Split a research question into claims, investigate sources, cross-check evidence, verify claims, and synthesize a concise answer.",
+    limits: {
+      maxAgents: 12,
+      maxConcurrentAgents: 4
+    },
+    inputs,
+    sandboxProfiles: ["readonly", "locked-down"],
+    phases: [
+      phase("Scope", [
+        agent(
+          "scope:claims",
+          "Break {{question}} into independently verifiable claims, source needs, scope boundaries {{scope}}, freshness requirement {{freshness}}, and likely stale assumptions. Use only the task input at this stage.",
+          { sandboxProfileId: "locked-down" }
+        )
+      ]),
+      phase("Investigate", [
+        agent(
+          "investigate:primary-sources",
+          "Investigate primary or official sources first from {{source}} for {{question}}. Return source titles, dates, authors or publishers, durable locators, key claims, and uncertainty. Mark missing retrieval needs explicitly.",
+          { sandboxProfileId: "readonly" }
+        ),
+        agent(
+          "investigate:counterpoints",
+          "Look for counterevidence, conflicting interpretations, stale claims, missing context, and scope violations for {{question}}. Prefer official or primary sources; label secondary-source-only claims.",
+          { sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Cross-check", [
+        agent(
+          "cross-check:evidence",
+          "Cross-check important claims across sources, dates, definitions, and uncertainty boundaries. Identify stale, unsupported, conditional, and conflicting claims with source locators.",
+          { sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Verify", [
+        agent(
+          "verify:claims",
+          "Verify each important claim against gathered evidence. Mark real, conditional, stale, unknown, or unsupported. The cw:result evidence array must cite durable source locators or local file paths.",
+          { requiresEvidence: true, sandboxProfileId: "readonly" }
+        )
+      ]),
+      phase("Synthesize", [
+        artifact(
+          "synthesis:report",
+          "Write a concise synthesis for {{question}} with answer, evidence, caveats, stale or uncertain claims, and open questions. Use only verified evidence in the task input; the cw:result evidence array must support the synthesis.",
+          { requiresEvidence: true, sandboxProfileId: "locked-down" }
+        )
+      ])
+    ]
+  });
+};

package/apps/workflow-app-framework-demo/app.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "id": "workflow-app-framework-demo",
+  "title": "Workflow App framework Demo",
+  "summary": "Small framework app showing inputs, phases, evidence gates, and sandbox profile hints.",
+  "version": "0.1.0",
+  "author": "COOLWHITE LLC",
+  "inputs": [
+    {
+      "name": "question",
+      "type": "string",
+      "required": true,
+      "description": "Question or implementation task this app should plan."
+    }
+  ],
+  "sandboxProfiles": [
+    "readonly",
+    "workspace-write"
+  ],
+  "compatibility": {
+    "minVersion": "0.1.9"
+  },
+  "metadata": {
+    "example": true
+  },
+  "workflow": {
+    "entrypoint": "workflow.js"
+  }
+}