compound-workflow 1.4.1 → 1.4.2

package/README.md

@@ -19,6 +19,7 @@ Runtime assets live in `src/.agents/` and `src/AGENTS.md`. Supports **Cursor**,
 ```bash
 npm install compound-workflow
 npx compound-workflow install
+npx compound-workflow install all
 ```
 
 **2. Choose how you use it:**
@@ -29,7 +30,7 @@ npx compound-workflow install
 
 **What Install does:** Merges `AGENTS.md` (preserves your Repo Config Block), creates standard dirs (`docs/`, `todos/`), writes `opencode.json` (for OpenCode), and—if the project has a `.cursor` directory—creates `.cursor/skills/<skill>`, `.cursor/agents`, `.cursor/commands`, and `.cursor/references` (symlinks into the package). All paths reference `node_modules/compound-workflow`; no file copying.
 
-**CLI options:** `--dry-run` (preview), `--root /path/to/project`, `--no-config` (skip Repo Config Block reminder), `--cursor` (create `.cursor` and wire Cursor symlinks even if `.cursor` does not already exist).
+**CLI options:** `all` / `--all` (full install shortcut; same as `--cursor`), `--dry-run` (preview), `--root /path/to/project`, `--no-config` (skip Repo Config Block reminder), `--cursor` (create `.cursor` and wire Cursor symlinks even if `.cursor` does not already exist).
 
 **Legacy (clone inside repo):** If you cloned this repo inside a host repo and need to copy files without npm, use `./scripts/sync-into-repo.sh` (copy only; does not update opencode.json). Prefer the npm + Install flow above.
 
@@ -159,6 +160,8 @@ Full “when to use what” and reference standards: [src/AGENTS.md](src/AGENTS.
 
 - **Independent review policy:** code/config changes require `/workflow:review` before workflow completion; docs-only changes are exempt.
 
+- **Standards baseline policy:** code/config changes must pass `skill: standards` as a hard gate (declarative flow, immutable transforms, maintainability boundaries) in both `/workflow:work` and `/workflow:review`; docs-only changes are exempt.
+
 - **Quality gate fallback:** if `lint_command` or `typecheck_command` is missing from repo config, workflow asks once for run-provided commands and continues only if they pass.
 
 - **Artifact policy:** do not create ad-hoc artifacts outside canonical outputs (`docs/plans`, `todos`, `docs/solutions`, `docs/metrics`) unless explicitly requested.

package/package.json

@@ -1 +1,31 @@
-{"name":"compound-workflow","version":"1.4.1","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"scripts":{"check:pack-readme":"node scripts/check-pack-readme.mjs"},"engines":{"node":">=18"},"devDependencies":{"@semantic-release/git":"^10.0.1","@semantic-release/npm":"^13.1.4","semantic-release":"^25.0.3"}}
+{
+  "name": "compound-workflow",
+  "version": "1.4.2",
+  "description": "Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cjerochim/compound-workflow.git"
+  },
+  "bin": {
+    "compound-workflow": "scripts/install-cli.mjs"
+  },
+  "files": [
+    "src",
+    "scripts",
+    ".cursor-plugin",
+    ".claude-plugin",
+    "skills"
+  ],
+  "scripts": {
+    "check:pack-readme": "node scripts/check-pack-readme.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.4",
+    "semantic-release": "^25.0.3"
+  }
+}

package/scripts/check-workflow-contracts.mjs

@@ -21,6 +21,11 @@ const requiredChecks = [
     pattern: "No ad-hoc artifacts outside canonical outputs",
     description: "canonical artifact policy in AGENTS",
   },
+  {
+    file: "src/AGENTS.md",
+    pattern: "Standards baseline is mandatory for code/config changes.",
+    description: "standards hard-gate policy in AGENTS",
+  },
   {
     file: "README.md",
     pattern: "If docs conflict:",
@@ -31,6 +36,11 @@ const requiredChecks = [
     pattern: "code/config changes require `/workflow:review`",
     description: "README review gate policy",
   },
+  {
+    file: "README.md",
+    pattern: "Standards baseline policy:",
+    description: "README standards baseline guardrail",
+  },
   {
     file: "src/.agents/commands/workflow/plan.md",
     pattern: "Contract precedence:",
@@ -62,6 +72,16 @@ const requiredChecks = [
     pattern: "workflow_complete: false (pending /workflow:review current)",
     description: "implementation-complete pending-review status in work command",
   },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "Standards Compliance Gate (REQUIRED for code/config changes)",
+    description: "required standards gate in work command",
+  },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "This gate cannot run until the isolation/worktree gate is passed and recorded (`gate_status: passed`).",
+    description: "standards gate ordering with worktree gate",
+  },
   {
     file: "src/.agents/commands/workflow/review.md",
     pattern: "Contract precedence:",
@@ -82,6 +102,26 @@ const requiredChecks = [
     pattern: "what was skipped and why",
     description: "review skipped-pass disclosure requirement",
   },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "standards_compliance: pass|pass-with-notes|fail",
+    description: "review standards compliance output field",
+  },
+  {
+    file: "src/.agents/commands/workflow/review.md",
+    pattern: "standards `MUST` violations => blocking finding and review recommendation `fail`",
+    description: "review must-violation fail criteria",
+  },
+  {
+    file: "src/.agents/skills/standards/SKILL.md",
+    pattern: "## Mandatory Baseline (Declarative, Immutable, Maintainable)",
+    description: "standards mandatory baseline section",
+  },
+  {
+    file: "src/.agents/skills/standards/SKILL.md",
+    pattern: "### MUST NOT",
+    description: "standards must-not checklist",
+  },
 ];
 
 const forbiddenChecks = [
@@ -100,6 +140,11 @@ const forbiddenChecks = [
     pattern: "skip specialist reviewers by default",
     description: "legacy skip-by-default specialist reviewer wording",
   },
+  {
+    file: "src/.agents/commands/workflow/work.md",
+    pattern: "Follow project coding standards (see AGENTS.md)",
+    description: "legacy advisory-only coding standards wording in work command",
+  },
 ];
 
 const failures = [];

package/scripts/install-cli.mjs

@@ -2,7 +2,7 @@
 /**
  * compound-workflow install
  * One action: opencode.json (load from package) + AGENTS.md merge + dirs + Repo Config Block.
- * Run from project: npx compound-workflow install [--root <dir>] [--dry-run] [--no-config]
+ * Run from project: npx compound-workflow install [all|--all] [--root <dir>] [--dry-run] [--no-config]
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -14,11 +14,12 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function usage(exitCode = 0) {
   const msg = `
 Usage:
-  npx compound-workflow install [--root <projectDir>] [--dry-run] [--no-config] [--cursor]
+  npx compound-workflow install [all|--all] [--root <projectDir>] [--dry-run] [--no-config] [--cursor]
 
 One action: writes opencode.json (loads from package), merges AGENTS.md, creates dirs,
 and prompts for Repo Config Block (unless --no-config).
 
+  all, --all    Full install shortcut (enables Cursor integration; creates .cursor if needed)
   --root <dir>   Project directory (default: cwd)
   --dry-run      Print planned changes only
   --no-config   Skip Repo Config Block prompt (only write opencode.json + AGENTS.md + dirs)
@@ -35,6 +36,7 @@ function parseArgs(argv) {
     if (a === "--dry-run") out.dryRun = true;
     else if (a === "--no-config") out.noConfig = true;
     else if (a === "--cursor") out.cursor = true;
+    else if (a === "--all" || a === "all") out.cursor = true;
     else if (a === "--root") {
       const v = argv[i + 1];
       if (!v) usage(1);
@@ -309,7 +311,7 @@ function ensureCursorSkills(targetRoot, dryRun, cursorReady) {
   const blocked = [];
   for (const name of skillNames) {
     const linkPath = path.join(skillsDir, name);
-    const targetRel = path.join("..", "..", "..", "node_modules", "compound-workflow", "src", ".agents", "skills", name);
+    const targetRel = path.join("..", "..", "node_modules", "compound-workflow", "src", ".agents", "skills", name);
     const targetAbs = path.resolve(path.dirname(linkPath), targetRel);
     let needCreate = true;
     try {
@@ -345,12 +347,53 @@ function verifyCursorIntegration(targetRoot) {
   for (const check of checks) {
     const linkPath = path.join(cursorDir, check.rel);
     const expectedAbs = path.join(targetRoot, "node_modules", "compound-workflow", "src", ".agents", check.rel);
-    if (!symlinkPointsTo(linkPath, expectedAbs)) issues.push(`${check.name} is missing or not linked to package`);
+    if (!fs.existsSync(linkPath)) issues.push(`${check.name} is missing`);
+    else {
+      const stat = fs.lstatSync(linkPath);
+      if (stat.isSymbolicLink() && !symlinkPointsTo(linkPath, expectedAbs)) {
+        issues.push(`${check.name} symlink points to unexpected target`);
+      }
+    }
+  }
+
+  const packageSkillsDir = path.join(packageRoot, "src", ".agents", "skills");
+  if (fs.existsSync(packageSkillsDir)) {
+    const missingSkills = [];
+    for (const name of fs.readdirSync(packageSkillsDir)) {
+      const skillPath = path.join(packageSkillsDir, name);
+      if (!fs.statSync(skillPath).isDirectory()) continue;
+      if (!fs.existsSync(path.join(skillPath, "SKILL.md"))) continue;
+      const cursorSkill = path.join(cursorDir, "skills", name, "SKILL.md");
+      if (!fs.existsSync(cursorSkill)) missingSkills.push(name);
+    }
+    if (missingSkills.length) {
+      issues.push(
+        `.cursor/skills is missing ${missingSkills.length} package skill(s), e.g. ${missingSkills[0]}`
+      );
+    }
   }
 
-  const workCommand = path.join(cursorDir, "commands", "workflow", "work.md");
-  if (!fs.existsSync(workCommand)) {
-    issues.push(".cursor/commands/workflow/work.md is not reachable after integration");
+  const packageRoots = [
+    { label: "commands", pkgDir: path.join(packageRoot, "src", ".agents", "commands"), cursorSubdir: "commands" },
+    { label: "agents", pkgDir: path.join(packageRoot, "src", ".agents", "agents"), cursorSubdir: "agents" },
+    { label: "references", pkgDir: path.join(packageRoot, "src", ".agents", "references"), cursorSubdir: "references" },
+  ];
+  for (const item of packageRoots) {
+    if (!fs.existsSync(item.pkgDir)) continue;
+    const pkgFiles = walkFiles(item.pkgDir, () => true);
+    let missingCount = 0;
+    let firstMissing = null;
+    for (const abs of pkgFiles) {
+      const rel = path.relative(item.pkgDir, abs);
+      const targetFile = path.join(cursorDir, item.cursorSubdir, rel);
+      if (!fs.existsSync(targetFile)) {
+        missingCount++;
+        if (!firstMissing) firstMissing = rel;
+      }
+    }
+    if (missingCount) {
+      issues.push(`.cursor/${item.label} is missing ${missingCount} package file(s), e.g. ${firstMissing}`);
+    }
   }
   return issues;
 }
@@ -359,7 +402,7 @@ function ensureCursorIntegration(targetRoot, dryRun, forceCursor) {
   const cursorDir = path.join(targetRoot, ".cursor");
   let cursorReady = fs.existsSync(cursorDir);
   if (!fs.existsSync(cursorDir)) {
-    if (!forceCursor) return { issues: [] };
+    if (!forceCursor) return { issues: [], status: "skipped-no-cursor" };
     if (dryRun) console.log("[dry-run] Would create .cursor directory (Cursor)");
     else {
       fs.mkdirSync(cursorDir, { recursive: true });
@@ -388,7 +431,7 @@ function ensureCursorIntegration(targetRoot, dryRun, forceCursor) {
   if (!dryRun) {
     for (const issue of verifyCursorIntegration(targetRoot)) issues.push(issue);
   }
-  return { issues };
+  return { issues, status: "configured" };
 }
 
 function writeOpenCodeJson(targetRoot, dryRun) {
@@ -540,6 +583,11 @@ function main() {
   ensureSkillsSymlink(targetRoot, args.dryRun);
   reportOpenCodeIntegration(targetRoot, args.dryRun);
   const cursorReport = ensureCursorIntegration(targetRoot, args.dryRun, args.cursor);
+  if (cursorReport.status === "skipped-no-cursor") {
+    console.log("Cursor integration: skipped (.cursor missing). Run install with `all` or `--cursor` to create it.");
+  } else {
+    console.log("Cursor integration: verified skills, agents, commands, and references.");
+  }
   writeAgentsMd(targetRoot, args.dryRun);
   ensureDirs(targetRoot, args.dryRun);
 

package/src/.agents/commands/install.md

@@ -1,8 +1,8 @@
 ---
 name: install
 invocation: install
-description: Install compound-workflow in this project (one action)—opencode.json, AGENTS.md, dirs, and Repo Config Block.
-argument-hint: "[--dry-run] [--root <path>] [--no-config]"
+description: Install compound-workflow in this project (one action)—opencode.json, AGENTS.md, dirs, Repo Config Block, and optional Cursor wiring.
+argument-hint: "[all|--all] [--dry-run] [--root <path>] [--no-config] [--cursor]"
 ---
 
 # /install
@@ -24,6 +24,7 @@ Run in the **workspace root** (or the directory the user specifies):
 
 ```bash
 npx compound-workflow@latest install
+npx compound-workflow@latest install all
 ```
 
 Or with a specific root and flags:
@@ -32,11 +33,14 @@ Or with a specific root and flags:
 npx compound-workflow install --root /path/to/project
 npx compound-workflow install --dry-run
 npx compound-workflow install --no-config
+npx compound-workflow install --cursor
 ```
 
+- **all / --all**: Full install shortcut; same as `--cursor` (creates `.cursor` if missing, then wires skills/agents/commands/references).
 - **--dry-run**: Print planned changes only; no writes.
 - **--root &lt;path&gt;**: Target project directory (default: current directory).
 - **--no-config**: Skip Repo Config Block reminder; only write opencode.json, AGENTS.md merge, and dirs.
+- **--cursor**: Force Cursor integration (create `.cursor` if missing, then wire skills/agents/commands/references).
 
 Do not copy files from a compound-workflow clone; the Install CLI uses the package from `node_modules/compound-workflow`.
 

package/src/.agents/commands/workflow/review.md

@@ -103,6 +103,11 @@ Protected artifacts:
 
 - `Task learnings-researcher(<target context>)` (related prior solutions)
 - `Task lint(<changed files context>)` only if `lint_command` is configured in the Repo Config Block
+- Run the standards compliance pass using `skill: standards` as mandatory baseline for code/config changes:
+  - evaluate declarative flow
+  - evaluate immutable transforms
+  - evaluate maintainability boundaries
+  - evaluate hidden mutable state
 - Verify agentic executability from plan/todo artifacts when available:
   - access prerequisites are explicit
   - validation commands are explicit and reproducible
@@ -139,6 +144,7 @@ Then perform the main review synthesis across:
 - risk and failure modes
 - operational considerations (monitoring, rollback)
 - readability/maintainability
+- standards compliance using `skill: standards` (MUST/MUST NOT baseline)
 
 ### Phase 4: Synthesis + Verdict
 
@@ -147,11 +153,18 @@ Provide:
 - Review recommendation: `pass | pass-with-notes | fail`
 - `review_independence_mode: independent|degraded`
 - `verdict_confidence: normal|degraded` (use `degraded` only when `review_independence_mode=degraded`)
+- `standards_compliance: pass|pass-with-notes|fail`
+  - `fail`: one or more standards MUST violations (blocking)
+  - `pass-with-notes`: no MUST violations, but SHOULD-level maintainability concerns
+  - `pass`: no material standards violations
 - Top risks (1–5 bullets)
 - Findings list:
   - severity (`critical | high | medium | low`)
   - evidence (file references or commands/output)
   - recommended action (concise)
+  - standards classification:
+    - standards `MUST` violations => blocking finding and review recommendation `fail`
+    - standards `SHOULD` violations => non-blocking finding and review recommendation `pass-with-notes`
 - Independence evidence summary:
   - what independent pass ran
   - what was skipped and why

package/src/.agents/commands/workflow/work.md

@@ -394,7 +394,7 @@ The input must be a plan file path.
    - The plan should reference similar code - read those files first
    - Match naming conventions exactly
    - Reuse existing components where possible
-   - Follow project coding standards (see AGENTS.md)
+   - Load and follow `skill: standards` as the mandatory baseline for declarative, immutable, maintainable implementation quality
    - When in doubt, grep for similar implementations
 
  3. **Test Continuously**
@@ -453,11 +453,30 @@ The input must be a plan file path.
 
    Docs-only runs may skip this handoff using the docs-only review exemption.
 
-3. **Final Validation**
+3. **Standards Compliance Gate (REQUIRED for code/config changes)**
+
+   For code/config changes, standards compliance is a hard gate before todo completion:
+
+   - Use `skill: standards` as the source of truth.
+   - This gate cannot run until the isolation/worktree gate is passed and recorded (`gate_status: passed`).
+   - Record standards evidence in todo Work Log using the standards evidence format:
+     - declarative flow
+     - immutable transforms
+     - maintainability boundaries
+     - hidden mutable state check
+   - If any mandatory standards line fails:
+     - do not rename todo to `*-complete-*.md`
+     - move todo back to `pending`
+     - add `tags: [blocker]`
+     - record blocking rationale + remediation steps in Work Log
+
+   Docs-only runs: mark this gate `not_applicable` and continue.
+
+4. **Final Validation**
    - All todo files created for this plan are marked complete
    - All tests pass
    - Linting/typechecking/formatting checks pass (configured or run-provided via ask-once fallback)
-   - Code follows existing patterns
+   - Code follows existing patterns and passes the standards compliance gate
    - UI validation completed (if applicable)
    - No console errors or warnings
    - Scope contract satisfied:
@@ -465,14 +484,14 @@ The input must be a plan file path.
      - `migration`: migration verification and rollback checks are documented as passing
      - `full_remediation`: scoped remediation goals are complete per `completion_expectation`
 
-4. **Update Plan Status**
+5. **Update Plan Status**
 
    If the input document has YAML frontmatter with a `status` field, update it to `completed`:
    ```
    status: active  →  status: completed
    ```
 
-5. **Notify User**
+6. **Notify User**
      - Summarize what was completed
      - Note any follow-up work needed
      - Suggest next steps if applicable

package/src/.agents/skills/standards/SKILL.md

@@ -5,6 +5,43 @@ description: General coding practices, implementation styles, and patterns for t
 
 # Altai Code Standards
 
+## Mandatory Baseline (Declarative, Immutable, Maintainable)
+
+These rules are mandatory for code/config implementation work. They are pass/fail gates, not advisory guidance.
+
+### MUST
+
+- **MUST keep orchestration declarative** in containers/controllers: describe state transitions and event flow explicitly instead of imperative step-by-step control logic.
+- **MUST use immutable transforms** for domain and controller data operations (`input -> output`), returning new values instead of mutating existing objects/arrays.
+- **MUST keep domain logic in pure entity functions** (no side effects, no hidden mutable module state, no IO in entity transforms/predicates).
+- **MUST keep maintainability boundaries clear**:
+  - containers wire/select/send and avoid business rules
+  - controllers manage state transitions and delegate reusable logic to entities
+  - presentation components remain UI-focused
+- **MUST keep branching complexity controlled** with early exits and extracted helpers when conditional logic grows.
+
+### MUST NOT
+
+- **MUST NOT implement mutation-heavy imperative handlers** that modify shared state in-place across multiple steps.
+- **MUST NOT use hidden mutable accumulators** (`let` variables mutated through control flow) when a pure transform is feasible.
+- **MUST NOT mix business decision logic into containers/presentation** when it belongs in domain entities/controllers.
+- **MUST NOT allow branching sprawl** in controllers/containers (deep nesting, chained `else-if`, or nested ternaries for workflow logic).
+- **MUST NOT complete code/config work without standards evidence** recorded in work/review outputs.
+
+### Required Evidence Format (Work and Review)
+
+Use this format when reporting standards compliance in execution or review evidence:
+
+```markdown
+standards_compliance:
+- declarative_flow: pass|fail (evidence: file:line)
+- immutable_transforms: pass|fail (evidence: file:line)
+- maintainability_boundaries: pass|fail (evidence: file:line)
+- hidden_mutable_state: pass|fail (evidence: file:line)
+```
+
+If any mandatory line is `fail`, code/config work is not complete.
+
 ## Core Principles
 
 1. **Simplicity over cleverness** - Prefer straightforward solutions

package/src/AGENTS.md

@@ -66,6 +66,7 @@ If workflow documents conflict, resolve them in this order:
 - **Spike governance is explicit and ordered.** Risky plans must evaluate spike need, spike candidates must declare initial priority/dependencies/unblocks/timebox/deliverable, triage confirms those assumptions, and `/workflow:work` executes blocking spikes before dependent build todos.
 - **Agentic access/testability is mandatory in planning.** Every plan must include an executable access + validation contract so work/review can run deterministically.
 - **Independent review is required for code/config changes.** `/workflow:review` must emit `review_independence_mode: independent|degraded`, plus independence evidence and skipped-pass disclosure.
+- **Standards baseline is mandatory for code/config changes.** `/workflow:work` and `/workflow:review` must apply `skill: standards` as a hard gate for declarative flow, immutable transforms, and maintainability boundaries.
 - **Todo completion requires evidence.** A todo may move to `complete` only after success criteria evidence and quality gate evidence are recorded in Work Log.
 - **Blockers change todo state immediately.** Blocked work must move from `ready` back to `pending` with `tags: [blocker]` and an options+recommendation decision record.
 - **Quality gates are enforced with ask-once fallback.** If `lint_command` or `typecheck_command` is missing, ask once per run and continue only when commands are provided and pass.