@difflab/difflab-cli 0.7.1 → 0.8.1

package/README.md

@@ -31,7 +31,7 @@ Initialization requires a GitHub HTTPS or SSH origin and never creates a Git rep
 
 If initialization is interrupted, retry `difflab init <PROJECT_KEY>`; matching partial links and database rows can be reused, but conflicting paths require manual inspection. Do not delete the shared database to repair a repository link.
 
-The `project_context({ cwd })` MCP tool inspects initialized repositories without creating files or applying migrations. If it reports missing or inconsistent setup, load the portable `skills/difflab-init/SKILL.md` in your client's Agent Skills directory and follow its CLI steps. Existing `todo_*` MCP tools remain available.
+The `project_context({ cwd })` MCP tool inspects initialized repositories without creating files or applying migrations. Existing `todo_*` MCP tools remain available.
 
 ## MCP setup
 
@@ -66,11 +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`, and `flow-instance`.
+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`.
 
 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.
 
-The portable `skills/difflab-plan`, `skills/difflab-review`, and `skills/difflab-flow` directories contain natural-language agent workflows for these templates. Install each skill in your client's Agent Skills directory. The MCP-only `log_append({"path":"/absolute/physical/project-store/plans/YYMMDD-name/logs.txt","message":"Phase started"})` tool creates an append-only progress log on first use; pass the physical path, not the `.difflab` symlink. There is no log CLI command.
+The portable `skills/difflab-plan`, `skills/difflab-review`, `skills/difflab-flow`, `skills/difflab-explore`, `skills/difflab-adr`, and `skills/difflab-poc` directories contain natural-language agent workflows for these templates. Install each skill in your client's Agent Skills directory. The MCP-only `log_append({"path":"/absolute/physical/project-store/plans/YYMMDD-name/logs.txt","message":"Phase started"})` tool creates an append-only progress log on first use; pass the physical path, not the `.difflab` symlink. There is no log CLI command.
 
 ## Flow definitions and runs
 

package/dist/index.js

@@ -48446,13 +48446,23 @@ var architecture_decision_record_default = `# [Decision: problem and chosen solu
 
 ### [Option A]
 
-- Good: [reason.]
-- Bad: [reason.]
+#### Pros
+
+- [Benefit.]
+
+#### Cons
+
+- [Drawback.]
 
 ### [Option B]
 
-- Good: [reason.]
-- Bad: [reason.]
+#### Pros
+
+- [Benefit.]
+
+#### Cons
+
+- [Drawback.]
 
 ## Decision Outcome
 
@@ -48792,6 +48802,162 @@ This is the frozen execution snapshot. Include only selected executable steps; n
 `;
 var init_flow_instance = () => {};
 
+// templates/exploration-summary.md
+var exploration_summary_default = `# Exploration: {{topic}}
+
+- **Status:** research in progress
+- **Started:** {{YYYY-MM-DD}}
+- **Updated:** {{YYYY-MM-DD}}
+- **Scope:** {{question and constraints}}
+
+## Question
+
+{{What is being investigated, and why?}}
+
+## Findings
+
+{{Evidence-backed findings with links to research notes. Separate facts from inference.}}
+
+## Prior art and options
+
+{{Existing codebase approaches, comparable open-source implementations, and distinct possible directions. No recommendation is required.}}
+
+## Proposals
+
+{{Optional: links to proposals/*.md. If research-only, say "Not requested".}}
+
+## Evidence and freshness
+
+{{Fetched primary-source URLs, dates accessed and relevant versions; note what changed since the previous revision, if any.}}
+
+## Unknowns and next questions
+
+{{Unverified claims, constraints to confirm, and follow-up research.}}
+
+## Revisit history
+
+{{For updates, date, request (including a revisit without feedback), revision number, and changed evidence. Never replace earlier revisions.}}
+`;
+var init_exploration_summary = () => {};
+
+// templates/exploration-research.md
+var exploration_research_default = `# Research: {{angle}}
+
+- **Exploration:** {{topic}}
+- **Researched:** {{YYYY-MM-DD}}
+- **Scope:** {{angle and constraints}}
+
+## Existing approaches and prior art
+
+{{Local code paths and comparable external projects; distinguish direct observations from inference.}}
+
+## Evidence
+
+{{Findings with inline citations to fetched primary documentation, source code, or release notes. Cite specific URLs and relevant versions/dates.}}
+
+## Library and tool landscape
+
+{{Relevant alternatives, maintenance activity, licensing, compatibility, and integration constraints. Say when these were not verified.}}
+
+## Trade-offs
+
+{{Supported benefits, drawbacks, and applicability to this repository.}}
+
+## Unknowns
+
+{{Gaps, stale evidence, conflicting sources, and follow-up checks.}}
+
+## Sources fetched
+
+- {{Title \u2014 primary URL \u2014 accessed YYYY-MM-DD \u2014 version/commit where applicable \u2014 what this source supports}}
+`;
+var init_exploration_research = () => {};
+
+// templates/exploration-proposal.md
+var exploration_proposal_default = `# Proposal: {{distinct approach}}
+
+- **Exploration:** {{topic}}
+- **Status:** option, not a decision
+
+## Fit
+
+{{When this approach makes sense and the constraints it meets.}}
+
+## Evidence and prior art
+
+{{Link to research notes, fetched primary sources, and analogous implementations. Label inferences.}}
+
+## Design shape
+
+{{Integration boundary, likely components and interfaces, without writing implementation code or a task plan. Use Mermaid if a diagram clarifies structure.}}
+
+## Trade-offs
+
+{{Costs, risks, maintenance and licensing considerations, and differences from other approaches.}}
+
+## Open questions
+
+{{Unverified claims and checks needed before choosing this approach.}}
+
+## Sources
+
+- {{Primary URL \u2014 accessed YYYY-MM-DD \u2014 version/commit where relevant}}
+`;
+var init_exploration_proposal = () => {};
+
+// templates/poc-readme.md
+var poc_readme_default = `---
+base_commit: '{{full SHA of origin/main at branch creation}}'
+---
+
+# PoC: {{name}}
+
+> Experimental branch only. Do not merge into production or publish as a release.
+
+## Purpose
+
+{{Question to answer and the smallest useful success criterion.}}
+
+## Setup and tasks
+
+{{Tool versions, dependency installation, environment inputs, and required services.}}
+
+| Task             | Command                   | Purpose                                           | Observed result              |
+| ---------------- | ------------------------- | ------------------------------------------------- | ---------------------------- |
+| Build            | \`mise run {{build-task}}\` | {{Build the experiment}}                          | {{Actual result or pending}} |
+| Test             | \`mise run {{test-task}}\`  | {{Validate the experimental behavior}}            | {{Actual result or pending}} |
+| Run {{approach}} | \`mise run {{run-task}}\`   | {{Run this prototype; repeat for every approach}} | {{Actual result or pending}} |
+
+{{Explain any genuinely inapplicable build/test task and its alternative validation. Identify unrun checks explicitly.}}
+
+## Code map
+
+{{Focused submodules, their responsibilities and small public APIs, entrypoints, and minimal examples. Keep the experiment direct and avoid speculative abstractions or giant implementation files.}}
+
+## Alternatives
+
+- {{Alternative or variation to compare, if any.}}
+
+## Experiments
+
+| Approach     | What changed | How to run    | Result          |
+| ------------ | ------------ | ------------- | --------------- |
+| {{approach}} | {{scope}}    | \`{{command}}\` | {{observation}} |
+
+## Learnings
+
+- {{Evidence-based result, caveat, and what remains unknown.}}
+
+## Compare with main at branch creation
+
+The \`base_commit\` is the full SHA of \`origin/main\` when this branch was created; do not update it when main moves. Compare this PoC with its starting point using \`git diff <base_commit> HEAD\`.
+
+## Disposition
+
+{{Follow-up decision or experiment; freeze with an annotated tag, never merge this branch.}}
+`;
+var init_poc_readme = () => {};
+
 // templates/examples/plan-feature.md
 var plan_feature_default = `# Invite teammates to a project
 
@@ -49309,6 +49475,10 @@ var init_source = __esm(() => {
   init_pull_request_description();
   init_flow_definition();
   init_flow_instance();
+  init_exploration_summary();
+  init_exploration_research();
+  init_exploration_proposal();
+  init_poc_readme();
   init_plan_feature();
   init_plan_migration();
   init_design_service();
@@ -49329,7 +49499,11 @@ var init_source = __esm(() => {
     { 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: "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,
@@ -49342,6 +49516,10 @@ var init_source = __esm(() => {
     "pull-request-description.md": pull_request_description_default,
     "flow-definition.md": flow_definition_default,
     "flow-instance.md": flow_instance_default,
+    "exploration-summary.md": exploration_summary_default,
+    "exploration-research.md": exploration_research_default,
+    "exploration-proposal.md": exploration_proposal_default,
+    "poc-readme.md": poc_readme_default,
     "examples/plan-feature.md": plan_feature_default,
     "examples/plan-migration.md": plan_migration_default,
     "examples/design-service.md": design_service_default,
@@ -51908,7 +52086,7 @@ function createProgram(write = console.log, version = "0.1.0", options = {}) {
 
 // src/index.ts
 init_errors3();
-var version2 = "0.7.1";
+var version2 = "0.8.1";
 try {
   await createProgram(console.log, version2).parseAsync(process.argv);
 } catch (error) {

package/package.json

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