zwicky

zwicky is an MIT-licensed, offline command-line tool for General Morphological Analysis: define a problem, create a morphological box, record cross-consistency judgments, and generate the internally consistent product or feature configurations that survive.

It is designed to be driven by people or AI agents:

• JSON output by default
• plain-text project stores that are easy to diff
• stateless commands that read and write local files
• no runtime dependencies
• no network access

Install

pip install -e .

Or run without installing:

python -m zwicky init bottle --problem "Design a smart water bottle"

Quick Start

zwicky init bottle --problem "Design a smart water bottle"

zwicky -C bottle dim add mechanism --values "uv light,filter,reminder"
zwicky -C bottle dim add user --values "athletes,office workers,parents"
zwicky -C bottle dim add form --values "cap module,built in,clip on"

zwicky -C bottle cca set mechanism.uv-light user.parents --verdict tension --reason "Safety messaging must be explicit"
zwicky -C bottle cca set mechanism.filter form.clip-on --verdict incompatible --reason "Filter needs inline water path"

zwicky -C bottle config generate
zwicky -C bottle config list --human
zwicky -C bottle config stats

Commands

zwicky [-C <project-dir>] <command> ...

zwicky init <name> --problem "..."
zwicky -C <project-dir> guide
zwicky -C <project-dir> status

zwicky -C <project-dir> stakeholders add --name "Customers" --description "..." [--kind customer]
zwicky -C <project-dir> stakeholders list
zwicky -C <project-dir> stakeholders rm <name>

zwicky -C <project-dir> dim add <name> --values a,b,c
zwicky -C <project-dir> dim list
zwicky -C <project-dir> dim rm <name>

zwicky -C <project-dir> value add <dim> <value>
zwicky -C <project-dir> value rm  <dim> <value>

zwicky -C <project-dir> cca set <valA> <valB> --verdict incompatible|tension|ok --reason "..."
zwicky -C <project-dir> cca list
zwicky -C <project-dir> cca gaps

zwicky -C <project-dir> config generate
zwicky -C <project-dir> config list [--promising]
zwicky -C <project-dir> config show <cfg_id>
zwicky -C <project-dir> config promote <cfg_id> [--unpromote]
zwicky -C <project-dir> config stats

zwicky -C <project-dir> report html [--path report.html]
zwicky -C <project-dir> report memo [--path memo.md]

zwicky -C <project-dir> edsl build
zwicky -C <project-dir> edsl run [--model <model-name>]
zwicky -C <project-dir> edsl report [--path stakeholder-results.html]

All commands emit JSON unless --human is supplied.

After zwicky init, prefer zwicky -C <project-dir> ... for later commands. This avoids path mistakes in agents that run parallel shell calls from changing working directories. Do not run commands from inside .zwicky/, and do not use legacy command shapes such as zwicky add-dim; the supported form is zwicky dim add.

Agent Guidance

zwicky guide is more than a command suggester. It returns:

• the current methodological phase
• the next command to run
• a short General Morphological Analysis brief
• phase-specific agent instructions
• quality checks for the current phase
• references for deeper background

Example:

zwicky guide --human

The guidance emphasizes the core discipline of the method: build the design space first, judge cross-consistency second, and only then evaluate which surviving configurations are promising.

The guide also includes collaboration rules for agent use:

• ask a small number of yes/no or multiple-choice clarifying questions before mutating the project
• present proposed dimensions, values, and eliminations for user approval
• proceed with reasonable assumptions only when the user explicitly authorizes "yolo mode"
• write client-facing reports as structured design-space exploration, avoiding internal tool names and preserving assumptions, eliminations, tensions, and validation steps

Reports

Compile the current project into either an audit report or a decision memo:

zwicky report html --path report.html
zwicky report memo --path memo.md

report html writes a standalone audit artifact with the decision question, dimensions, compatibility judgments, promoted configurations, validation notes, and report-writing guidance.

report memo writes an editable Markdown decision memo scaffold. It is recommendation-first, gives promoted configurations concept names, includes rationale placeholders, carries forward tensions as risks, and ends with validation steps and open questions. It is intended to be polished by an agent or human with domain judgment.

Relative paths are written inside the visible project directory.

Stakeholder Evaluation With EDSL

Register stakeholders whose perspectives should be used to evaluate the levels inside each dimension:

zwicky stakeholders add \
  --name "Small business customer" \
  --description "A time-constrained buyer comparing agent packages for concrete work outcomes." \
  --kind "customer segment"

zwicky stakeholders add \
  --name "Internal engineering" \
  --description "The team responsible for supportability, implementation effort, and quality controls." \
  --kind "internal team"

Then build EDSL artifacts:

zwicky edsl build

This creates git-backed EDSL .ep packages under .zwicky/edsl/:

• agent_list.ep: an EDSL AgentList built from registered stakeholders
• scenario_list.ep: one scenario per dimension, carrying level names and context
• survey.ep: an EDSL survey with QuestionRank questions for each dimension and free-text reason questions
• jobs.ep: an EDSL Jobs package combining the survey and stakeholder agent list
• manifest.json: paths and next steps

It also writes stakeholder-perspectives.html in the visible project directory as a scaffold for presenting perspectives. Use the EDSL results as perspective evidence, not as automatic decisions; the reasons are usually more useful than the rank order alone.

To run the survey with EDSL:

zwicky edsl run

edsl run loads .env from the visible project directory, shells out to the EDSL CLI with the saved jobs.ep package, saves results.ep under .zwicky/edsl/, and writes stakeholder-results.html.

edsl report regenerates stakeholder-results.html from an existing results.ep without rerunning the survey. The HTML shows a stakeholder by dimension ranking matrix, first-choice summary, and rationale cards.

Store Format

A project is a visible workspace directory named <name>/. Internal bookkeeping is stored under <name>/.zwicky/:

• project.json: name, problem statement, status
• dimensions.json: dimensions and values
• cca.jsonl: one cross-consistency judgment per line
• configs.jsonl: generated surviving configurations

End users should not normally edit .zwicky/ by hand. Reports and other client-facing outputs are written in the visible project workspace.

Value references can use full IDs such as mechanism.uv-light, or bare value names when unambiguous.