@difflab/difflab-cli 0.9.0 → 0.11.0

package/README.md

@@ -66,7 +66,11 @@ difflab-cli templates list
 difflab-cli templates scaffold spec-driven-plan docs/plans first-plan.md --cwd /absolute/project/path
 ```
 
-The CLI defaults `--cwd` to its current directory. The MCP server exposes `template_list({})` and `scaffold({"name":"spec-driven-plan","cwd":"/absolute/project/path","path":"docs/plans","filename":"first-plan.md"})`. Both interfaces take a hyphenated template name, a relative destination **directory** (`path`, or `.` for `cwd`), and a separate **filename**. MCP always requires an absolute existing `cwd`. Missing destination directories are created. Available names: `spec-driven-plan`, `software-architecture-design`, `architecture-decision-record`, `product-requirements-document`, `code-review`, `planning-intent`, `ui-component-architecture`, `pull-request-description` (adapted from Diffpi's PR template), `flow-definition`, `flow-instance`, `exploration-summary`, `exploration-research`, `exploration-proposal`, and `poc-readme`.
+The CLI defaults `--cwd` to its current directory. The MCP server exposes `template_list({})` and `scaffold({"name":"spec-driven-plan","cwd":"/absolute/project/path","path":"docs/plans","filename":"first-plan.md"})`. Both interfaces take a hyphenated template name, a relative destination **directory** (`path`, or `.` for `cwd`), and a separate **filename**. MCP always requires an absolute existing `cwd`. Missing destination directories are created. Available names: `spec-driven-plan`, `software-architecture-design`, `architecture-decision-record`, `product-requirements-document`, `agents`, `code-review`, `code-review-rubric`, `planning-intent`, `ui-component-architecture`, `pull-request-description` (adapted from Diffpi's PR template), `flow-definition`, `flow-instance`, `exploration-summary`, `exploration-research`, `exploration-proposal`, and `poc-readme`.
+
+Reviews scaffold `code-review` as `REVIEW.md` and `code-review-rubric` as `rubric.yaml` in `.difflab/reviews/YYMMDD-name`. The installed rubric is `~/.difflab/templates/code-review-rubric.yaml`. Fill its criterion results during the review. File-scoped criteria require a path-tagged result for every changed source file. Function findings can include `file:line` locations. Evidence guidance and review instructions stay in the review skill, outside the lean YAML template.
+
+Use `difflab-cli templates scaffold agents . AGENTS.md --cwd /absolute/project/path` to start repository guidance. Fill the prompts with known rules and remove unused prompts. The template separates Hard Rules, Organization, Style, and Testing. Hard Rules name required task runners and repository tools. Organization separates directory layout from section headers, code ordering, and grouping within files. Review addressing saves explicit user repository rules immediately and marks inferred or uncertain rules with `[Proposed]`. It asks before reorganizing existing guidance to match the template and adapts the existing structure if permission is declined. It retains terse file-level organization rules and keeps guidance within 500 soft-wrapped source lines.
 
 On first use, missing bundled templates and filled examples are copied to `~/.difflab/templates` and `~/.difflab/templates/examples`. Edit the installed templates to customize future documents. Later runs add missing files but never replace existing ones, even after an upgrade. Examples are for reference, not selectable templates. Copying is literal: prompts and placeholders are not substituted. An unknown name, missing or invalid source, unsafe path, symlink, or existing destination causes an error; destination files are never overwritten. The target directory must remain inside `cwd` and the filename must be a single file name without separators. The one symlink exception is an initialized repository's `.difflab` link to its own user project store: `templates scaffold spec-driven-plan .difflab/plans/YYMMDD-name PLAN.md --cwd /absolute/repo` works in Git worktrees as well. To restore a bundled default, move your installed copy aside before listing again.
 

package/dist/index.js

@@ -48618,6 +48618,45 @@ var product_requirements_document_default = `# [User outcome or product change]
 `;
 var init_product_requirements_document = () => {};
 
+// templates/agents.md
+var agents_default = `# Repository Guidance
+
+<!-- Fill the prompts with known repository rules and remove unused prompts. Write terse, imperative bullets in simple English. Use soft wrapping and keep the whole file at or below 500 source lines, including headings and blank lines. Replace contradictory rules, merge duplicates, and prune less important guidance when adding rules. Prefix inferred or uncertain rules with [Proposed]; omit the prefix only for rules the user explicitly asks to add or says must always apply in this repo. Link to maintained docs for details; omit architecture explanations, README repetition, and code snippets. -->
+
+## Hard Rules
+
+- Prefer the repository's existing task-runner tasks. See [task definitions](path-to-task-definitions).
+- [State required scaffolding and repository management tools. Link to their configuration.]
+- [Add other essential repository constraints.]
+
+## Organization
+
+### Repository layout
+
+- [State directory layout and file naming conventions. Link to maintained docs for details.]
+
+### File layout
+
+- [State prescribed section headers, code ordering, and grouping within each file type.]
+- [Retain terse rules for import, type, API, hook, and helper placement.]
+
+## Style
+
+### Languages
+
+- [Replace this heading with each language used here and add its rules.]
+
+### Frameworks
+
+- [Replace this heading with each framework that needs specific rules.]
+
+## Testing
+
+- [State where unit, integration, and end-to-end tests belong.]
+- [State test naming, structure, shared helper, and validation rules. Link to task definitions.]
+`;
+var init_agents = () => {};
+
 // templates/code-review.md
 var code_review_default = `# Review: [change or pull request]
 
@@ -48625,6 +48664,8 @@ var code_review_default = `# Review: [change or pull request]
 - **Intent:** [stated objective and source]
 - **Reviewer:** [name]
 
+[Apply root and applicable nested AGENTS.md rules throughout every section. Repository rules take precedence over generic rubric conventions. Cite violations under the relevant section.]
+
 ## Intent Delivery
 
 [Does the change actually deliver the intended behavior? What is missing or outside scope?]
@@ -48635,7 +48676,7 @@ var code_review_default = `# Review: [change or pull request]
 
 ## Semantic Organization
 
-[Do modules have clear roles and useful public APIs? Identify mixed responsibilities and unclear ownership. Refactor or simplify at the scope needed to make the change understandable, including across files. Keep unrelated work out of scope.]
+[Do modules have clear roles and useful public APIs? Are exported types meaningful for the module role? Are methods and classes easy to discover and use? Identify mixed responsibilities and unclear ownership. Refactor or simplify at the scope needed to make the change understandable, including across files. Keep unrelated work out of scope.]
 
 ## Maintainability
 
@@ -48643,11 +48684,11 @@ var code_review_default = `# Review: [change or pull request]
 
 ## Reliability/Testing
 
-[Prioritize end-to-end application behavior, then module behavior through public APIs, then focused unit behavior with public APIs first. Name missing observable contracts or regressions; do not demand coverage of every function or a percentage. Check semantic grouping, clear Arrange/Act/Assert blocks, fixtures, and existing shared helpers. Flag walls of repeated setup or interleaved actions/assertions that hide the behavior. Report executed checks and limits honestly.]
+[Prioritize end-to-end application behavior, then module behavior through public APIs, then focused unit behavior with public APIs first. Flag tests that only verify external dependencies rather than the repository's source behavior or integration contract. Require test names to identify the function or functionality tested and its expected behavior, regardless of grouping style. Name missing observable contracts or regressions; do not demand coverage of every function or a percentage. Check semantic grouping, clear Arrange/Act/Assert blocks, fixtures, and existing shared helpers. Flag walls of repeated setup or interleaved actions/assertions that hide the behavior. Report executed checks and limits honestly.]
 
-## Repository Guidance
+## Documentation
 
-[List root/applicable nested AGENTS.md paths and material deviations in changed files. Cite actual rules, including code/test organization and helper placement where prescribed. If none applies or guidance could not be read, say so. Keep this assessment brief.]
+[Flag walls of text, complex language, and text that only restates the implementation. Require concise, simple-English explanations. Prefer diagrams when they clarify structures, flows, or relationships better than long prose.]
 
 ## Performance
 
@@ -48655,11 +48696,11 @@ var code_review_default = `# Review: [change or pull request]
 
 ## Security
 
-[Report clear security defects, including exposed secrets or broken authorization/trust boundaries. Deepen the audit for an explicit security focus; avoid unrelated hardening requests. State SKIPPED with a short reason when a deeper audit is not warranted.]
+[Optional: run this dimension only when explicitly requested, including a security focus. Otherwise state that it was not selected. Report clear security defects discovered by other dimensions without claiming a security audit. Avoid unrelated hardening requests.]
 
 ## Change Requests
 
-Use short comments in simple English. State the problem and its effect directly. Phrase recommendations as suggestions with \u201CLet's\u201D, \u201CI suggest\u201D, or \u201CI recommend\u201D, usually in one to three sentences total. Use the scope that fixes the problem, including a refactor when needed. Group repeated instances of one cause. Omit nitpicks, minor optimizations, and speculative findings. End each generated request and response with its model attribution quote. Preserve human text unchanged.
+Every generated comment and reply must use simple English and be as short as possible. Include a suggested change when a concrete fix is available. State the issue and its effect directly. Phrase recommendations with \u201CLet's\u201D, \u201CI suggest\u201D, or \u201CI recommend\u201D. Include a short snippet or suggested patch only when it clarifies the fix. Use the scope that fixes the problem, including a refactor when needed. Group repeated instances of one cause. Omit repeated context, nitpicks, minor optimizations, and speculative findings. End each generated request and response with its model attribution quote. Preserve human text unchanged.
 
 ### [file:line \u2014 request]
 
@@ -48685,10 +48726,185 @@ Use short comments in simple English. State the problem and its effect directly.
 ## Verification and Limits
 
 - **Checks run:** [command and result.]
-- **Not verified:** [environment, path, or behavior not checked.]
+- **Not verified:** [environment, path, behavior, or applicable repository guidance that could not be checked.]
+- **Rubric:** [path to the copied YAML rubric with completed criterion results. Disclose missing, pending, skipped, or stale results.]
 `;
 var init_code_review = () => {};
 
+// templates/code-review-rubric.yaml
+var code_review_rubric_default = `version: 1
+worker_defaults:
+  model: sol
+  reasoning_effort: medium
+review:
+  base_revision: null
+  head_revision: null
+  working_tree: null
+  changed_files: []
+  exclusions: []
+  section_reviewers: []
+sections:
+  - title: Intent Delivery
+    criteria:
+      - id: intent.objective
+        scope: review
+        default_severity: blocking
+        issue: The change contradicts its stated intent or omits required behavior.
+        results: []
+      - id: intent.scope
+        scope: review
+        default_severity: consider
+        issue: The change includes work outside its stated scope.
+        results: []
+  - title: Readability
+    criteria:
+      - id: readability.function-names
+        scope: file
+        default_severity: consider
+        issue: >-
+          Function or other names misrepresent behavior, hide side effects, or break established naming conventions.
+        results: []
+      - id: readability.structure
+        scope: file
+        default_severity: consider
+        issue: The changed flow is materially hard to follow.
+        results: []
+  - title: Semantic Organization
+    criteria:
+      - id: organization.roles
+        scope: file
+        default_severity: consider
+        issue: A module mixes responsibilities or its imports, exports, or public API obscure its role.
+        results: []
+      - id: organization.architecture
+        scope: review
+        default_severity: consider
+        issue: Files or classes break the established architecture or module patterns.
+        results: []
+      - id: organization.api-ergonomics
+        scope: applicable-file
+        applies_when: Added or modified public APIs, exported types, methods, or classes.
+        default_severity: consider
+        issue: Public APIs expose types unrelated to the module role or are hard to discover and use.
+        results: []
+      - id: organization.new-files
+        scope: applicable-file
+        applies_when: Added source files that introduce a module or submodule. A rename alone does not qualify.
+        default_severity: consider
+        issue: >-
+          A new file lacks a justified module boundary or contains functions that belong in an existing module.
+        results: []
+      - id: organization.file-structure
+        scope: file
+        default_severity: consider
+        issue: A file breaks the project-prescribed structure or declaration order.
+        results: []
+  - title: Maintainability
+    criteria:
+      - id: maintainability.concepts
+        scope: review
+        default_severity: consider
+        issue: >-
+          New fields, types, wrappers, helpers, dependencies, or layers lack a justified use and add needless complexity.
+        results: []
+      - id: maintainability.complexity
+        scope: applicable-file
+        applies_when: >-
+          Files with added or changed executable functions. For new functions, assess whether the introduced decision paths are justified.
+        default_severity: consider
+        issue: Cyclomatic complexity grows without justification from the required behavior.
+        results: []
+      - id: maintainability.utilities
+        scope: review
+        default_severity: consider
+        issue: Duplicated state or behavior, or inline work, makes a function harder to read or maintain.
+        results: []
+      - id: maintainability.packages
+        scope: review
+        default_severity: consider
+        issue: >-
+          Custom code recreates functionality that an established, widely used package suitably provides.
+        results: []
+  - title: Reliability/Testing
+    criteria:
+      - id: testing.correctness
+        scope: file
+        default_severity: blocking
+        issue: The changed code produces incorrect behavior.
+        results: []
+      - id: testing.application
+        scope: review
+        default_severity: consider
+        issue: Required behavior or a meaningful regression lacks test evidence.
+        results: []
+      - id: testing.relevance
+        scope: applicable-file
+        applies_when: Added or modified test files.
+        default_severity: consider
+        issue: >-
+          A test verifies external dependency behavior without establishing behavior of the repository's own source code.
+        results: []
+      - id: testing.names
+        scope: applicable-file
+        applies_when: Added or modified test files.
+        default_severity: consider
+        issue: >-
+          A test name does not identify the function or functionality tested and its expected behavior.
+        results: []
+      - id: testing.arrange-act-assert
+        scope: applicable-file
+        applies_when: Added or modified test files.
+        default_severity: consider
+        issue: >-
+          Test grouping or interleaved setup, actions, and assertions hide the scenario or expected result.
+        results: []
+      - id: testing.fixtures
+        scope: applicable-file
+        applies_when: Added or modified tests, fixtures, test setup, or test utility files.
+        default_severity: consider
+        issue: >-
+          Repeated setup, unsuitable fixtures, or recreated shared utilities obscure tests or duplicate existing helpers.
+        results: []
+  - title: Documentation
+    criteria:
+      - id: documentation.conciseness
+        scope: applicable-file
+        applies_when: Added or modified documentation, including documentation comments.
+        default_severity: consider
+        issue: Long, dense, or complex text makes documentation hard to understand.
+        results: []
+      - id: documentation.redundancy
+        scope: applicable-file
+        applies_when: Added or modified documentation, including documentation comments.
+        default_severity: consider
+        issue: Documentation repeats the implementation or other text without adding useful context.
+        results: []
+      - id: documentation.visuals
+        scope: applicable-file
+        applies_when: Added or modified documentation that explains structures, flows, or relationships.
+        default_severity: consider
+        issue: A long textual explanation obscures information that a diagram would make clearer.
+        results: []
+  - title: Performance
+    criteria:
+      - id: performance.regressions
+        scope: review
+        default_severity: consider
+        issue: The change causes a material performance regression.
+        results: []
+  - title: Security
+    optional: true
+    criteria:
+      - id: security.defects
+        scope: review
+        default_severity: blocking
+        issue: The change exposes secrets or breaks authorization or a trust boundary.
+        results: []
+    worker:
+      reasoning_effort: high
+`;
+var init_code_review_rubric = () => {};
+
 // templates/planning-intent.md
 var planning_intent_default = `# Intent: [short name]
 
@@ -49701,13 +49917,15 @@ Add invitation resend and cancellation in a separate change.
 var init_pull_request_feature = () => {};
 
 // src/templates/source.ts
-var catalog, contents, embeddedSource;
+var contents, catalog, embeddedSource;
 var init_source = __esm(() => {
   init_spec_driven_plan();
   init_software_architecture_design();
   init_architecture_decision_record();
   init_product_requirements_document();
+  init_agents();
   init_code_review();
+  init_code_review_rubric();
   init_planning_intent();
   init_ui_component_architecture();
   init_pull_request_description();
@@ -49727,28 +49945,14 @@ var init_source = __esm(() => {
   init_component_dialog();
   init_component_navigation();
   init_pull_request_feature();
-  catalog = [
-    { name: "spec-driven-plan", description: "Spec-driven implementation plan" },
-    { name: "software-architecture-design", description: "Software architecture design" },
-    { name: "architecture-decision-record", description: "Architecture decision record" },
-    { name: "product-requirements-document", description: "Product requirements document" },
-    { name: "code-review", description: "Thorough code review" },
-    { name: "planning-intent", description: "Planning intent for a user to fill in" },
-    { name: "ui-component-architecture", description: "UI component design and implementation" },
-    { name: "pull-request-description", description: "Draft pull request description" },
-    { name: "flow-definition", description: "Reusable global Agent Skill flow definition" },
-    { name: "flow-instance", description: "Frozen repository-local flow run" },
-    { name: "exploration-summary", description: "Source-grounded technical exploration summary" },
-    { name: "exploration-research", description: "Technical exploration research notes" },
-    { name: "exploration-proposal", description: "Optional technical exploration approach" },
-    { name: "poc-readme", description: "Disposable proof-of-concept branch README" }
-  ];
   contents = {
     "spec-driven-plan.md": spec_driven_plan_default,
     "software-architecture-design.md": software_architecture_design_default,
     "architecture-decision-record.md": architecture_decision_record_default,
     "product-requirements-document.md": product_requirements_document_default,
+    "agents.md": agents_default,
     "code-review.md": code_review_default,
+    "code-review-rubric.yaml": code_review_rubric_default,
     "planning-intent.md": planning_intent_default,
     "ui-component-architecture.md": ui_component_architecture_default,
     "pull-request-description.md": pull_request_description_default,
@@ -49769,6 +49973,28 @@ var init_source = __esm(() => {
     "examples/component-navigation.md": component_navigation_default,
     "examples/pull-request-feature.md": pull_request_feature_default
   };
+  catalog = [
+    { name: "spec-driven-plan", description: "Spec-driven implementation plan" },
+    { name: "software-architecture-design", description: "Software architecture design" },
+    { name: "architecture-decision-record", description: "Architecture decision record" },
+    { name: "product-requirements-document", description: "Product requirements document" },
+    { name: "agents", description: "Concise repository rules for AGENTS.md" },
+    { name: "code-review", description: "Thorough code review" },
+    {
+      name: "code-review-rubric",
+      description: "YAML code review criteria and per-file results",
+      asset: "code-review-rubric.yaml"
+    },
+    { name: "planning-intent", description: "Planning intent for a user to fill in" },
+    { name: "ui-component-architecture", description: "UI component design and implementation" },
+    { name: "pull-request-description", description: "Draft pull request description" },
+    { name: "flow-definition", description: "Reusable global Agent Skill flow definition" },
+    { name: "flow-instance", description: "Frozen repository-local flow run" },
+    { name: "exploration-summary", description: "Source-grounded technical exploration summary" },
+    { name: "exploration-research", description: "Technical exploration research notes" },
+    { name: "exploration-proposal", description: "Optional technical exploration approach" },
+    { name: "poc-readme", description: "Disposable proof-of-concept branch README" }
+  ];
   embeddedSource = {
     catalog,
     assets: Object.keys(contents),
@@ -49802,7 +50028,8 @@ class TemplateService {
     return [...this.source.catalog];
   }
   async scaffoldFromTemplate(name, cwd, path, filename) {
-    if (!this.source.catalog.some((item) => item.name === name)) {
+    const template = this.source.catalog.find((item) => item.name === name);
+    if (!template) {
       throw new UnknownTemplateError(`Unknown template: ${name}`);
     }
     if (!path.trim() || isAbsolute7(path)) {
@@ -49812,8 +50039,8 @@ class TemplateService {
       throw new TemplateError("filename must be a single non-empty file name");
     }
     await this.installMissing();
-    const installed = await resolvePath(this.home, join6(".difflab", "templates", `${name}.md`));
-    const contents = await readMarkdown(installed);
+    const installed = await resolvePath(this.home, join6(".difflab", "templates", template.asset ?? `${name}.md`));
+    const contents = await readTemplate(installed);
     const destination = path.startsWith(".difflab/") ? await this.projectDestination(cwd, path.slice(".difflab/".length), filename) : await ensurePathDirsExist(join6(path, filename), cwd);
     try {
       await createExclusive(destination, contents);
@@ -49846,7 +50073,7 @@ class TemplateService {
         if ((await lstat7(destination)).isSymbolicLink()) {
           throw new TemplateSourceError(`Installed template asset is a symlink: ${destination}`);
         }
-        await readMarkdown(destination);
+        await readTemplate(destination);
       } catch (error) {
         if (!hasErrorCode(error, "ENOENT"))
           throw error;
@@ -49856,7 +50083,7 @@ class TemplateService {
         } catch (writeError) {
           if (!hasErrorCode(writeError, "EEXIST"))
             throw writeError;
-          await readMarkdown(destination);
+          await readTemplate(destination);
         }
       }
     }
@@ -49874,7 +50101,7 @@ async function readSource(source, asset) {
     throw new TemplateSourceError(`Cannot read template asset: ${asset}`, { cause: error });
   }
 }
-async function readMarkdown(path) {
+async function readTemplate(path) {
   let handle;
   try {
     handle = await open3(path, constants2.O_RDONLY | constants2.O_NOFOLLOW);
@@ -49932,7 +50159,8 @@ var init_tools4 = __esm(() => {
   init_service();
   templateInfo = object({
     name: string2(),
-    description: string2()
+    description: string2(),
+    asset: string2().optional()
   });
   templateListOutput = object({ result: array(templateInfo) });
   scaffoldOutput = object({
@@ -50134,7 +50362,7 @@ function agentAdapter(name) {
   return Object.hasOwn(agentAdapters, name) ? agentAdapters[name] : undefined;
 }
 var agentAdapters, agentNames;
-var init_agents = __esm(() => {
+var init_agents2 = __esm(() => {
   init_adapter();
   init_claude_code();
   init_codex();
@@ -50177,7 +50405,7 @@ async function setupMcpClients(clients, write) {
   write("Restart or reload the selected client to use the Difflab MCP tools.");
 }
 var init_setup = __esm(() => {
-  init_agents();
+  init_agents2();
 });
 
 // src/mcp/index.ts
@@ -52324,7 +52552,7 @@ function createProgram(write = console.log, version = "0.1.0", options = {}) {
 
 // src/index.ts
 init_errors3();
-var version2 = "0.9.0";
+var version2 = "0.11.0";
 try {
   await createProgram(console.log, version2).parseAsync(process.argv);
 } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@difflab/difflab-cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "private": false,
   "description": "A minimal Bun CLI starter built with Commander",
   "license": "Apache-2.0",