edsger 0.76.0 → 0.78.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 edsger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,254 +1,139 @@
-# Edsger
+# edsger
 
-AI-powered software development CLI tool with comprehensive issue management, code review, and testing capabilities using Claude Code SDK and MCP integration.
+> Agentic CLI to **benchmark** repositories and **review** / **resolve** pull
+> requests against industrial-grade engineering standards.
 
-## Features
-
-### 🚀 Project Initialization
-
-- **Automated Documentation**: Uses Claude Code SDK to analyze your codebase and generate comprehensive documentation
-- **Phase Optimization**: Provides project context to all phases for better AI understanding
-- **Smart Analysis**: Automatically discovers tech stack, architecture, coding patterns, and conventions
-- **One-Command Setup**: Quick initialization with `edsger --init` - no manual documentation needed
-
-### 🔍 Code Review
-
-- **AI-Powered Reviews**: Uses Claude Code SDK for intelligent code analysis
-- **Git Integration**: Reviews uncommitted or staged changes automatically
-- **Configurable**: Customize patterns, exclusions, and review severity
-- **Hook-Friendly**: Designed for pre-commit hooks and CI/CD automation
-- **Detailed Output**: Clear feedback with blocking/warning/passing results
-
-### 🔧 Code Refactoring
-
-- **Intelligent Analysis**: AI-powered code quality and refactoring analysis
-- **Pattern Detection**: Identifies code smells, duplication, and technical debt
-- **Improvement Suggestions**: Provides prioritized recommendations for code improvement
-- **Interactive Mode**: Ask for confirmation before applying refactoring changes
-
-### 🎯 Issue Analysis
-
-- **MCP Integration**: Analyze issues using Model Context Protocol
-- **User Story Generation**: Create comprehensive user stories for issues
-- **Test Case Creation**: Generate detailed test cases with criticality levels
-- **Deduplication**: Avoid creating similar existing user stories and test cases
-- **Real-time Streaming**: Live analysis feedback with Claude Code SDK
-
-### 🎨 Technical Design
-
-- **Design Generation**: Create technical specifications for issues
-- **Architecture Planning**: Generate implementation roadmaps and technical details
-- **Integration Support**: Works with MCP for structured design output
-
-### 💻 Code Implementation
-
-- **Issue Implementation**: Automatically implement issues based on specifications
-- **Branch Management**: Creates feature branches and manages git workflow
-- **Code Generation**: AI-powered code writing with proper git integration
-
-### 🎭 Functional Testing
-
-- **Automated Testing**: Run Playwright-based functional tests for issues
-- **Test Execution**: Execute test cases with detailed reporting
-- **Status Tracking**: Monitor test results with pass/fail statistics
-
-### 🚀 Workflow Management
-
-- **Continuous Processing**: Monitor and process issues ready for development
-- **End-to-End Automation**: Complete issue lifecycle from analysis to testing
-- **Real-time Monitoring**: Live workflow processing with statistics and graceful shutdown
-
-## Installation
-
-```bash
-npm install edsger
-```
-
-## Usage
-
-### Project Initialization
+`edsger` runs the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
+over your code. The standards it applies (security, maintainability, testing,
+delivery, language-specific quality) live in
+[edsger-assets](https://github.com/stevenzg/edsger-assets) and are **fully
+overridable** — use the sensible defaults with zero config, or point edsger at
+your team's own standards.
 
 ```bash
-# Initialize .edsger directory - AI automatically generates documentation
-edsger --init
-
-# Verbose output to see the analysis process
-edsger --init --verbose
+npm install -g edsger        # or: npx edsger ...
+export ANTHROPIC_API_KEY=...  # required for the agent
 ```
 
-The init command uses Claude Code SDK to automatically:
-
-1. Analyze your codebase structure and files
-2. Discover technologies, frameworks, and dependencies
-3. Identify architectural patterns and design decisions
-4. Extract coding conventions and standards
-5. Generate comprehensive documentation in `.edsger/` directory
-
-Generated documentation files:
-
-- `project-overview.md` - Project description, goals, and core features
-- `tech-stack.md` - Technologies, frameworks, and tools used
-- `architecture.md` - System architecture and design decisions
-- `coding-guidelines.md` - Coding standards and conventions
-- `development-setup.md` - Development environment setup instructions
+## Commands
 
-These files provide rich context to all edsger phases for better code generation, analysis, and implementation. You can edit them manually to refine or add details.
+### `edsger benchmark`
 
-### Code Review
+Score the repository in the current directory and write a report to
+`.edsger/benchmark/` (`report.md` + `report.json`).
 
 ```bash
-# Review all uncommitted changes
-edsger --review
-
-# Review only staged changes
-edsger --review --staged
-
-# Review specific file patterns
-edsger --review --files "**/*.ts" "**/*.js"
-
-# Verbose output
-edsger --review --verbose
+edsger benchmark                 # score the current repo
+edsger benchmark -C ./service    # score another directory
+edsger benchmark --json          # also print JSON to stdout
+edsger benchmark --no-write      # don't write files into the repo
 ```
 
-### Code Refactoring
+The agent detects the project's language(s), loads the matching rubric, inspects
+the code, scores every criterion with evidence, and edsger aggregates the
+weighted total into a 0–100 score and a letter grade.
 
-```bash
-# Analyze and refactor code in current directory
-edsger --refactor
-
-# Verbose refactoring output
-edsger --refactor --verbose
-```
-
-### Issue Analysis
-
-```bash
-# Analyze an issue and generate user stories/test cases
-edsger --issue-analysis <issue-id>
-
-# Verbose analysis output
-edsger --issue-analysis <issue-id> --verbose
-```
+### `edsger pr-review <pr>` (requires `gh`)
 
-### Technical Design
+Review a pull request against the review standard. Previews by default; pass
+`--post` to submit the review (with inline comments) to GitHub.
 
 ```bash
-# Generate technical design for an issue
-edsger --technical-design <issue-id>
-
-# Verbose design output
-edsger --technical-design <issue-id> --verbose
+gh auth login
+edsger pr-review 123             # preview a review of PR #123
+edsger pr-review 123 --post      # submit it to GitHub
+edsger pr-review https://github.com/org/repo/pull/123 --repo org/repo
 ```
 
-### Code Implementation
+### `edsger pr-resolve <pr>` (requires `gh`)
 
-```bash
-# Implement issue code based on specifications
-edsger --implement <issue-id>
-
-# Verbose implementation output
-edsger --implement <issue-id> --verbose
-```
-
-### Functional Testing
+Address review feedback (or a specific instruction), edit the code, run the
+tests, and optionally commit & push.
 
 ```bash
-# Run functional tests for an issue
-edsger --test <issue-id>
-
-# Verbose test output
-edsger --test <issue-id> --verbose
+edsger pr-resolve 123                                   # apply fixes to the working tree
+edsger pr-resolve 123 --instruction "fix the failing CI test"
+edsger pr-resolve 123 --push                            # commit and push when done
 ```
 
-### Workflow Management
+## Customising standards
 
-```bash
-# Run continuous workflow processor
-edsger --workflow
+Zero config uses the bundled defaults. To customise, edsger resolves standards
+in this order (highest precedence last):
 
-# Run with verbose logging
-edsger --workflow --verbose
-```
+1. **Bundled** defaults (from edsger-assets).
+2. A **configured override** in `edsger.config.yaml` — a local path or a git repo.
+3. A repo-local **`.edsger/<kind>/`** directory.
+4. An explicit **`--standard <path>`** flag.
 
-### Default Behavior
+Layers merge by id, so you can override a single category weight or add one
+criterion without copying the whole rubric.
 
-```bash
-# Auto-detects mode based on environment:
-# - If EDSGER_PRODUCT_ID and EDSGER_MCP_TOKEN are set: workflow mode
-# - Otherwise: code review mode
-edsger
+```yaml
+# edsger.config.yaml
+model: claude-sonnet-4-6
+standards: git+https://github.com/acme/eng-standards#main
+# or per-kind:
+benchmark:
+  standards: ./standards
 ```
 
-## Configuration
-
-Create a configuration file (`.edsgerrc.json`, `edsger.config.js`, etc.):
-
-```json
-{
-  "patterns": ["**/*.js", "**/*.ts"],
-  "exclude": ["node_modules/**", "*.test.js"],
-  "severity": "error",
-  "maxFiles": 100,
-  "claude": {
-    "model": "sonnet",
-    "timeout": 120000
-  }
-}
+Drop a partial overlay into your repo to tweak the defaults:
+
+```yaml
+# .edsger/benchmark/base.yaml
+categories:
+  - id: security
+    weight: 30 # bump security's weight
+    criteria:
+      - id: threat-model
+        title: A documented threat model exists
+        guidance: Look for docs/threat-model.md or an equivalent.
 ```
 
-## Environment Variables
-
-### Required for Advanced Features (Issue Analysis, Technical Design, Implementation, Testing, Workflow)
-
-- `EDSGER_MCP_SERVER_URL`: MCP server URL for issue operations
-- `EDSGER_MCP_TOKEN`: Required authentication token for MCP server
-- `EDSGER_PRODUCT_ID`: Product ID for workflow management (optional for workflow mode)
-
-### Configuration Options
-
-- **patterns**: File patterns to include (default: common code files)
-- **exclude**: File patterns to exclude (default: tests, builds, node_modules)
-- **severity**: `"error"` (exit 1 on issues) or `"warning"` (exit 0 always)
-- **maxFiles**: Maximum files to review in one run
-- **claude.model**: Claude model to use (`sonnet`, `opus`, etc.)
-- **claude.timeout**: Timeout in milliseconds
+## Use it inside Claude Code
 
-## Git Hooks Integration
-
-Add to your `.git/hooks/pre-commit`:
+If you already have the CLI, one command wires up the `/benchmark`, `/pr-review`,
+and `/pr-resolve` skills in Claude Code — no marketplace or paths to remember:
 
 ```bash
-#!/bin/sh
-npx edsger --review --staged
+edsger skills install            # for the current user (all projects)
+edsger skills install --project  # or scope to ./.claude/skills
+edsger skills list               # see what's installed
+edsger skills uninstall          # remove them
 ```
 
-## Requirements
+This copies the skills into `~/.claude/skills/` and points them at the bundled
+standards. Open Claude Code and run `/benchmark`, `/pr-review`, or `/pr-resolve`.
 
-- Node.js >= 18.0.0
-- `@anthropic-ai/claude-code` SDK
-- MCP server for advanced issue operations (analysis, design, implementation, testing)
-- Playwright for functional testing (when using `--test` flag)
+**Without the CLI**, the same standards are also a Claude Code plugin:
 
-## Releasing
+```
+/plugin marketplace add stevenzg/edsger-assets
+/plugin install edsger@edsger-assets
+```
 
-Published from this directory using
-[semantic-release](https://github.com/semantic-release/semantic-release),
-driven by [Conventional Commit](https://www.conventionalcommits.org/)
-messages on `main` (`fix:` → patch, `feat:` → minor, `feat!:` /
-`BREAKING CHANGE:` → major).
+## Global options
+
+| Option                | Description                                                  |
+| --------------------- | ------------------------------------------------------------ |
+| `-C, --cwd <dir>`     | repository to operate on                                     |
+| `-m, --model <id>`    | agent model (default `claude-sonnet-4-6`, or `EDSGER_MODEL`) |
+| `--standard <path>`   | custom standards dir or file                                 |
+| `--assets <path>`     | override the entire assets root                              |
+| `--lang <id>`         | force a language, skipping detection                         |
+| `--max-turns <n>`     | max agentic turns                                            |
+| `--timeout <minutes>` | hard wall-clock limit per agent run (default 15)             |
+| `--json`              | machine-readable JSON on stdout                              |
+| `--dry-run`           | run the agent but make no persistent/external changes        |
+| `-v, --verbose`       | verbose logging                                              |
 
-```bash
-cd packages/edsger
-npm run release:preview   # dry-run, see the next version + notes
-npm run release           # publish to npm + push the git tag
-```
+## Requirements
 
-> **Important:** the `edsger-contract` and `edsger-tools` versions
-> referenced in `package.json` must already be on the npm registry
-> before this CLI can be installed. Always run the Changesets flow for
-> those two packages first — see [`RELEASING.md`](../../RELEASING.md)
-> in the repo root for the full sequence.
+- Node.js ≥ 18.17
+- `ANTHROPIC_API_KEY` for the agent
+- [GitHub CLI](https://cli.github.com) (`gh`), authenticated, for the PR commands
 
 ## License
 
-ISC
+MIT

package/assets/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 edsger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/README.md

@@ -0,0 +1,104 @@
+# edsger-assets
+
+Industrial-grade, opinionated **standards** that power the [`edsger`](https://www.npmjs.com/package/edsger) CLI.
+
+This repository is the canonical source of truth for:
+
+- **Benchmark rubrics** (`benchmark/`) — how a repository is scored for security,
+  maintainability, testing, documentation, delivery, and language-specific quality.
+- **PR review standards** (`review/`) — what a reviewer (human or agent) should look
+  for when reviewing a pull request, and how findings are prioritised.
+
+The content here encodes widely accepted engineering best practices (OWASP, the
+Twelve-Factor App, Google Engineering Practices, SLSA, Keep a Changelog, Semantic
+Versioning, language style guides, etc.) into machine-readable rubrics that an
+agent can apply consistently.
+
+These standards can be consumed three ways:
+
+1. **The [`edsger`](https://www.npmjs.com/package/edsger) CLI** — bundles these
+   assets and runs them with the Claude Agent SDK.
+2. **As a Claude Code plugin** — `/benchmark`, `/pr-review`, `/pr-resolve` skills
+   that work inside Claude Code with no CLI install (see below).
+3. **Raw YAML** — point any tooling at the files in `benchmark/` and `review/`.
+
+## Use inside Claude Code (no CLI install)
+
+This repository is also a Claude Code plugin marketplace. Add it and install the
+plugin to get the skills as slash commands:
+
+```
+/plugin marketplace add stevenzg/edsger-assets
+/plugin install edsger@edsger-assets
+```
+
+Then run `/benchmark`, `/pr-review`, or `/pr-resolve`. The skills read the same
+rubric YAML from this repo (`${CLAUDE_PLUGIN_ROOT}/benchmark/...`) and prefer the
+`edsger` CLI when it is installed, falling back to running natively with Claude
+Code's own tools.
+
+## Layout
+
+```
+edsger-assets/
+├── .claude-plugin/           # Claude Code plugin + marketplace manifests
+│   ├── plugin.json
+│   └── marketplace.json
+├── skills/                   # Claude Code skills (/benchmark, /pr-review, /pr-resolve)
+│   ├── benchmark/SKILL.md
+│   ├── pr-review/SKILL.md
+│   └── pr-resolve/SKILL.md
+├── manifest.yaml              # registry: versions, languages, default chains
+├── languages.yaml            # language detection heuristics (markers + globs)
+├── schema/
+│   ├── benchmark.schema.json # JSON Schema for a benchmark rubric
+│   └── review.schema.json    # JSON Schema for a review standard
+├── benchmark/
+│   ├── base.yaml             # language-agnostic baseline (always applied)
+│   ├── typescript.yaml       # overlays, merged on top of base
+│   ├── python.yaml
+│   ├── go.yaml
+│   ├── csharp.yaml
+│   ├── java.yaml
+│   └── dart.yaml
+└── review/
+    ├── base.yaml
+    ├── typescript.yaml
+    ├── python.yaml
+    ├── go.yaml
+    ├── csharp.yaml
+    ├── java.yaml
+    └── dart.yaml
+```
+
+## How standards are resolved
+
+`edsger` detects the project's language(s), loads `base` first, then merges any
+matching language overlays on top of it (overlay categories/criteria are added,
+and same-`id` entries are overridden). The result is a single effective standard.
+
+### Overriding these defaults
+
+Teams can override or extend everything without forking this repo. `edsger`
+resolves standards in this order (first match wins per file):
+
+1. A path passed on the CLI (`--standard <dir-or-file>`).
+2. A `.edsger/` directory inside the repository being analysed.
+3. A configured override in `edsger.config.*` (a local path or a git repo).
+4. These bundled defaults.
+
+So the zero-config experience uses these assets, while a team can drop a single
+YAML file into their repo to customise a category weight or add a criterion.
+
+## Versioning
+
+Assets follow [Semantic Versioning](https://semver.org/). The `manifest.yaml`
+`schemaVersion` changes only on a breaking schema change; individual standards
+carry their own `version`. See [CHANGELOG.md](./CHANGELOG.md).
+
+## Contributing
+
+New criteria must cite a recognised standard or a clearly justified best
+practice, be language-appropriate, and validate against the JSON Schemas in
+`schema/`. Keep guidance actionable — describe what "excellent" vs "poor" looks
+like so scoring is reproducible.