@openhands/extensions 0.0.1-alpha → 0.2.0

package/plugins/migration-scoring/skills/migration-report/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: migration-report
+description: Generate a comprehensive migration report summarizing quality scores and providing recommendations. Use after scoring a migration project.
+license: MIT
+compatibility: Requires migration_score.json and style_score.json files
+triggers:
+  - migration report
+  - migration summary
+  - quality report
+---
+
+Generate a comprehensive migration report that summarizes scores and provides actionable insights.
+
+**Prerequisites**: Migration quality scores and style scores must exist (see `migration-score-quality` and `migration-score-style` skills).
+
+## Report Structure
+
+### 1. Executive Summary
+
+- Overall migration health (High/Medium/Low confidence)
+- Key statistics: total files, average scores, score distribution
+- One-paragraph assessment for stakeholders
+
+### 2. Score Overview
+
+#### Coverage Statistics
+- Average coverage score
+- Files with coverage < 3 (needs attention)
+- Files with coverage = 5 (complete)
+
+#### Correctness Statistics
+- Average correctness score
+- Files with correctness < 3 (needs attention)
+- Files with correctness = 5 (verified)
+
+#### Style Statistics
+- Average style score per attribute
+- Common style issues identified
+
+### 3. Risk Assessment
+
+Categorize files into:
+- **Green**: Coverage ≥ 4, Correctness ≥ 4, Style ≥ 4
+- **Yellow**: Any score between 3-4
+- **Red**: Any score < 3
+
+### 4. Notable Findings
+
+#### Strengths
+- What was migrated well
+- Good patterns to replicate
+
+#### Weaknesses
+- Common issues across files
+- Patterns to avoid
+
+### 5. Recommendations
+
+Prioritized action items:
+1. **Critical** — Files with scores < 3
+2. **Important** — Files with scores 3-4
+3. **Nice to have** — Style improvements for green files
+
+### 6. Detailed Scores
+
+Include the raw scores for reference (or link to score files).
+
+## Output Format
+
+Generate the report as a Markdown file:
+
+```markdown
+# Migration Quality Report
+
+**Generated**: 2024-01-15
+**Project**: Customer Management System
+**Source**: COBOL (45 files)
+**Target**: Java (62 files)
+
+## Executive Summary
+
+Migration is at **MEDIUM confidence** with average coverage of 4.2/5 and 
+correctness of 4.0/5. Three files require immediate attention due to 
+incomplete business logic migration.
+
+## Score Overview
+
+### Coverage
+- Average: 4.2/5
+- Complete (5): 28 files (62%)
+- Needs attention (<3): 3 files (7%)
+
+...
+```
+
+## Tone and Audience
+
+- Write for technical stakeholders (architects, tech leads)
+- Be specific about issues (cite file names, line numbers if relevant)
+- Provide actionable recommendations, not vague suggestions
+- Acknowledge good work, not just problems
+
+## Data Sources
+
+Read scores from:
+- `migration_score.json` — Coverage and correctness scores
+- `style_score.json` — Style evaluation scores
+- `migration_mapping.json` — File mapping (for counts)
+
+## Example Recommendations
+
+**Good:**
+> "CALC001.java has coverage 2/5 because batch processing logic in 
+> CALC001.cbl lines 150-200 was not migrated. Implement the 
+> `processBatch()` method to match COBOL paragraph PROCESS-BATCH."
+
+**Bad:**
+> "Some files need more work."

package/plugins/migration-scoring/skills/migration-scoring-overview/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: migration-scoring
+description: Evaluate code migration quality with coverage, correctness, and style scoring. Generates executive reports with actionable recommendations.
+license: MIT
+compatibility: Requires completed migration with source and target code, Python 3.13 with uv
+triggers:
+  - migration scoring
+  - migration quality
+  - migration evaluation
+  - score migration
+---
+
+Comprehensive quality evaluation for code migration projects.
+
+## Overview
+
+This plugin evaluates completed migrations through multiple lenses:
+
+1. **Mapping** — Document source-to-target file relationships
+2. **Quality Scoring** — Measure coverage and correctness
+3. **Style Scoring** — Evaluate code quality and conventions
+4. **Reporting** — Generate executive summary with recommendations
+
+## Prerequisites
+
+- Completed migration with both source and target code present
+- Python 3.13 with `uv`
+- LLM API key (Anthropic or OpenAI)
+- Optional: Custom style rubric file
+
+## Quick Start
+
+```bash
+export LLM_API_KEY="your-api-key"
+export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"
+
+uv run python -m lc_sdk_examples.migration_scoring \
+  --src-path /path/to/migration/project \
+  --rubric-path /path/to/style_rubric.txt
+```
+
+## Workflow Phases
+
+### Phase 1: Migration Mapping
+
+See [../migration-mapping/SKILL.md](../migration-mapping/SKILL.md)
+
+Creates a source→target file mapping:
+- Identifies which target files implement each source file
+- Supports many-to-many relationships
+- Flags unmigrated source files
+
+**Output:** `migration_mapping.json`
+
+```json
+{
+  "CALC001.cbl": ["InvoiceCalculator.java", "TaxCalculator.java"],
+  "CUST002.cbl": ["CustomerService.java"]
+}
+```
+
+### Phase 2: Quality Scoring
+
+See [../score-quality/SKILL.md](../score-quality/SKILL.md)
+
+Scores each source file on:
+- **Coverage (1-5)**: How much functionality was migrated
+- **Correctness (1-5)**: How accurately behavior was preserved
+
+**Output:** `migration_score.json`
+
+```json
+{
+  "CALC001.cbl": {
+    "coverage": 4,
+    "correctness": 5,
+    "justification": "All calculation logic migrated..."
+  }
+}
+```
+
+### Phase 3: Style Scoring
+
+See [../score-style/SKILL.md](../score-style/SKILL.md)
+
+Evaluates target code against style guidelines:
+- Naming conventions
+- Code organization
+- Error handling
+- Documentation
+- Idiomaticity
+
+**Output:** `style_score.json`
+
+### Phase 4: Executive Report
+
+See [../migration-report/SKILL.md](../migration-report/SKILL.md)
+
+Generates a comprehensive report:
+- Overall health assessment
+- Score statistics and distribution
+- Risk categorization (Green/Yellow/Red)
+- Prioritized recommendations
+
+**Output:** `final_report.md`
+
+## Output Structure
+
+```
+your-project/
+├── .lc-sdk/
+│   ├── migration_mapping.json
+│   ├── migration_score.json
+│   ├── style_score.json
+│   └── final_report.md
+```
+
+## Scoring Criteria
+
+See [../score-quality/references/scoring-criteria.md](../score-quality/references/scoring-criteria.md) for the 1-5 scoring scales.
+
+### Risk Categories
+
+- **Green**: All scores ≥ 4
+- **Yellow**: Any score 3-4
+- **Red**: Any score < 3

package/plugins/migration-scoring/skills/score-quality/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: score-quality
+description: Score code migration quality based on coverage and correctness. Evaluates how well target code represents source functionality.
+license: MIT
+compatibility: Requires completed migration with source and target code
+triggers:
+  - migration quality
+  - migration score
+  - coverage score
+  - correctness score
+---
+
+Evaluate migration quality by scoring coverage and correctness for each source-target file pair.
+
+**Prerequisite**: A migration mapping file must exist (see `migration-mapping` skill).
+
+See [references/scoring-criteria.md](references/scoring-criteria.md) for the 1-5 scoring scales.
+
+## Output Format
+
+Save scores as a JSON file:
+
+```json
+{
+  "source_file_1.cbl": {
+    "coverage": 4,
+    "correctness": 5,
+    "justification": "All calculation logic migrated. Tax rounding matches COBOL behavior."
+  }
+}
+```
+
+## Evaluation Process
+
+For each source file and its mapped target files:
+
+1. **Identify key functionality** in the source
+   - Business logic, data operations, control flow, error handling
+
+2. **Check coverage** in the target
+   - Is each function/paragraph represented?
+   - Are all data fields and code paths covered?
+
+3. **Verify correctness**
+   - Do calculations produce the same results?
+   - Are edge cases handled the same way?
+
+4. **Document justification**
+   - Specific functionality present/missing
+   - Known discrepancies
+
+## Incremental Scoring
+
+If a score file already exists, update it with new scores rather than replacing it entirely.

package/plugins/migration-scoring/skills/score-quality/references/scoring-criteria.md

@@ -0,0 +1,30 @@
+# Migration Quality Scoring Criteria
+
+## Coverage Scale (1-5)
+
+| Score | Description |
+|-------|-------------|
+| 1 | Very low coverage — most functionality missing |
+| 2 | Low coverage — significant functionality missing |
+| 3 | Moderate coverage — some functionality missing |
+| 4 | High coverage — minor functionality missing |
+| 5 | Very high coverage — all functionality present |
+
+## Correctness Scale (1-5)
+
+| Score | Description |
+|-------|-------------|
+| 1 | Very low correctness — many inaccuracies |
+| 2 | Low correctness — significant inaccuracies |
+| 3 | Moderate correctness — some inaccuracies |
+| 4 | High correctness — minor inaccuracies |
+| 5 | Very high correctness — accurate representation |
+
+## Common Issues to Flag
+
+- Missing error handling
+- Hardcoded values that were configurable
+- Lost precision in numeric conversions
+- Missing validation rules
+- Incomplete data transformations
+- UI logic that wasn't migrated (acceptable if documented)

package/plugins/migration-scoring/skills/score-style/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: score-style
+description: Score migrated code against style guidelines and best practices. Evaluates code quality independent of functional correctness.
+license: MIT
+compatibility: Requires target code to evaluate
+triggers:
+  - style score
+  - code quality score
+  - style evaluation
+---
+
+Evaluate migrated code against style guidelines and best practices.
+
+This skill scores code quality aspects that are independent of functional correctness — focusing on readability, maintainability, and adherence to conventions.
+
+## Default Scoring Criteria
+
+Unless a custom rubric is provided, score on these attributes (1-5 scale):
+
+### Naming Conventions (1-5)
+- 1: Inconsistent or meaningless names
+- 3: Mostly follows conventions, some issues
+- 5: Clear, consistent, idiomatic names
+
+### Code Organization (1-5)
+- 1: Monolithic, hard to navigate
+- 3: Some structure, could be cleaner
+- 5: Well-organized, logical structure
+
+### Error Handling (1-5)
+- 1: Missing or swallowed exceptions
+- 3: Basic error handling present
+- 5: Comprehensive, appropriate error handling
+
+### Documentation (1-5)
+- 1: No documentation
+- 3: Some documentation, inconsistent
+- 5: Thorough, helpful documentation
+
+### Idiomaticity (1-5)
+- 1: Non-idiomatic, smells like translated code
+- 3: Mostly idiomatic, some foreign patterns
+- 5: Fully idiomatic, natural code
+
+## Output Format
+
+Save scores as a JSON file:
+
+```json
+{
+  "target_file_a.java": {
+    "naming_conventions": 4,
+    "code_organization": 3,
+    "error_handling": 5,
+    "documentation": 4,
+    "idiomaticity": 4,
+    "justification": "Good naming and error handling. Some methods could be extracted for better organization."
+  }
+}
+```
+
+## Custom Rubric
+
+If a custom rubric is provided, use its attributes and scoring criteria instead of the defaults. The rubric should define:
+- Attribute names
+- Score meanings for each level (1-5)
+- Examples of good/bad code for each attribute
+
+## Evaluation Guidelines
+
+### What to Look For
+
+**Positive indicators:**
+- Consistent naming (camelCase for Java, snake_case for Python)
+- Appropriate class/method sizes
+- Single responsibility principle followed
+- Meaningful comments (not obvious ones)
+- Standard library usage over custom implementations
+- Defensive programming practices
+
+**Negative indicators:**
+- Literal translations (COBOL-style Java)
+- God classes or methods
+- Magic numbers
+- Excessive comments or no comments
+- Reinvented wheels
+- Swallowed exceptions
+- Hardcoded values
+
+### Language-Specific Considerations
+
+**Java:**
+- Streams vs. for loops (both acceptable, but be consistent)
+- Optional vs. null checks
+- Record types for data classes
+- Builder pattern for complex objects
+
+**Python:**
+- Type hints
+- List comprehensions
+- Context managers
+- Pythonic idioms
+
+## Incremental Scoring
+
+If a score file already exists, update it with new scores rather than replacing it entirely.

package/plugins/onboarding/.plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "onboarding",
+  "version": "1.0.0",
+  "description": "Assess repository agent-readiness across five pillars, propose high-impact fixes, and generate repo-specific AGENTS.md files",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "onboarding",
+    "readiness",
+    "agents-md",
+    "agent-readiness",
+    "assessment",
+    "ai-readiness"
+  ]
+}

package/plugins/onboarding/README.md

@@ -0,0 +1,30 @@
+# Onboarding Plugin
+
+Get a repository ready for OpenHands (and other AI agents) to start being productive. This plugin bundles the skills and documentation needed to take a codebase from zero to agent-ready.
+
+## Quick Start
+
+Run the `setup-openhands` skill on any repository. It walks through everything needed in one pass: generates an AGENTS.md, creates setup and pre-commit scripts, and adds a PR review workflow.
+
+## Going Deeper
+
+Once the basics are in place, you can harden your repo's agent readiness:
+
+1. **`agent-readiness-report`** — evaluates the repo across five pillars and produces a scored report
+2. **`improve-agent-readiness`** — reads that report and proposes the highest-impact fixes, then implements them on request
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| [setup-openhands](skills/setup-openhands/) | One-pass setup: AGENTS.md, scripts, and PR review workflow |
+| [agent-readiness-report](skills/agent-readiness-report/) | Evaluate a repo's agent readiness across five pillars |
+| [improve-agent-readiness](skills/improve-agent-readiness/) | Propose and implement fixes from a readiness report |
+| [setup-agents-md](skills/setup-agents-md/) | Generate a repo-specific AGENTS.md |
+| [setup-pr-review](skills/setup-pr-review/) | Add automated AI code review to a repo |
+
+The last two skills (`setup-agents-md` and `setup-pr-review`) are called by `setup-openhands` — you typically won't need to run them directly.
+
+## Shared References
+
+The `agent-readiness-report` and `improve-agent-readiness` skills share the same evaluation criteria. The canonical file lives at `references/criteria.md` at the plugin root; each skill symlinks to it.

package/plugins/onboarding/references/criteria.md

@@ -0,0 +1,144 @@
+# Agent Readiness Criteria
+
+Features that make a codebase ready for AI-assisted development, organized into
+five pillars.  Derived from cluster analysis of 123 repositories, but written to
+be tool-agnostic.  Every feature answers one question: *if this is missing, what
+goes wrong for the agent?*
+
+---
+
+## Pillar 1 · Agent Instructions
+
+How the repo tells AI agents what to do, what to avoid, and how the codebase
+works.  This is the highest-signal pillar — it's the difference between an agent
+that understands the project and one that's guessing.
+
+| # | Feature | What to look for | Evidence |
+|---|---------|------------------|----------|
+| 1 | **Agent instruction file** | A dedicated file telling agents how to work in this repo — conventions, banned patterns, common commands | `AGENTS.md`, `CLAUDE.md`, `COPILOT.md`, `CONVENTIONS.md` at root |
+| 2 | **AI IDE configuration** | Settings or rules for AI-powered editors/IDEs | `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`, `.github/instructions/`, `.claude/settings.json` |
+| 3 | **Multi-model support** | Instructions that work across different AI models/tools, not locked to one vendor | 2+ distinct agent config types from features 1–2 present in same repo |
+| 4 | **Agent skills or capabilities** | Packaged, reusable abilities the agent can invoke | `.claude/skills/`, `.factory/skills/`, `skill.md` files, tool definition files |
+| 5 | **Tool server configuration** | Config for agent tool protocols (lets agents use external tools) | `.mcp.json`, `mcp.config.js`, tool server manifests |
+| 6 | **Agent prompt library** | Pre-built prompts for common tasks in this repo | `.github/prompts/`, `prompts/` directory, prompt template files |
+| 7 | **Component-level agent guidance** | Different parts of the codebase have their own agent instructions | `AGENTS.md` or instruction files in subdirectories (e.g. `frontend/AGENTS.md`, `api/CLAUDE.md`) |
+| 8 | **README with build/run/test** | README includes the commands to build, run, and test the project | `README.md` containing code blocks with build/install/test commands |
+| 9 | **Contributing guide** | How to contribute — code style, PR process, commit conventions | `CONTRIBUTING.md`, `docs/contributing.md`, contributing section in README |
+| 10 | **Architecture documentation** | High-level overview of how the system is structured and why | `ARCHITECTURE.md`, `docs/architecture/`, Mermaid/PlantUML diagrams, `doc/design/` |
+| 11 | **API documentation** | Reference docs for the project's interfaces | `openapi.yaml`, generated HTML docs, `doc.go` files, Swagger UI, `api-docs/` |
+| 12 | **Inline code documentation** | Doc comments, docstrings — agents read these to understand intent | JSDoc `/** */` blocks, Python docstrings, GoDoc comments, RDoc `#` blocks, Rust `///` |
+| 13 | **Runnable examples** | Working example code the agent can study and imitate | `examples/` directory, `_examples/`, example apps with their own READMEs |
+| 14 | **Changelog** | History of what changed and how entries should be written | `CHANGELOG.md`, `CHANGES.md`, `HISTORY.md`, release notes in GitHub Releases |
+| 15 | **Environment variable documentation** | Template or docs for required env vars | `.env.example`, `.env.template`, env var table in README or docs |
+| 16 | **Documentation site or directory** | Organized docs beyond the README | `docs/` directory, Docusaurus/Sphinx/MkDocs/VitePress config, published doc site |
+| 17 | **Decision records** | Documented reasoning behind past architectural choices | `doc/adr/`, `decisions/`, `rfcs/`, numbered markdown decision files |
+| 18 | **Module-level READMEs** | Individual packages/modules have their own READMEs | `packages/*/README.md`, `libs/*/README.md`, per-crate/per-module READMEs |
+
+---
+
+## Pillar 2 · Feedback Loops
+
+How quickly and clearly the agent learns whether its changes are correct.  Fast,
+clear feedback is the difference between an agent that converges on a solution
+and one that spirals.
+
+| # | Feature | What to look for | Evidence |
+|---|---------|------------------|----------|
+| 19 | **Linter** | Static analysis that catches bugs and style issues | `.eslintrc.*`, `ruff.toml`, `.golangci.yml`, `clippy.toml`, `pylintrc`, lint config in `pyproject.toml` |
+| 20 | **Formatter** | Auto-formatter that enforces consistent style | `.prettierrc`, `rustfmt.toml`, `[tool.black]` in pyproject.toml, `gofmt`/`goimports` in CI |
+| 21 | **Type checking** | Static type system or type checker | `tsconfig.json` with `strict`, `mypy.ini`, `[tool.mypy]`, `py.typed` marker, Go (inherent) |
+| 22 | **Pre-commit hooks** | Checks that run before commit — catches issues before CI | `.pre-commit-config.yaml`, `.husky/`, `lefthook.yml`, `lint-staged` config |
+| 23 | **Unit tests** | Tests for individual components | `*_test.go`, `*_test.py`, `*.spec.ts`, `test/`, `__tests__/`, test runner config |
+| 24 | **Integration tests** | Tests that verify components work together | `test/integration/`, `tests/e2e/`, API test suites, test files with service dependencies |
+| 25 | **End-to-end tests** | Full system/browser tests | Playwright config, Cypress config, Selenium tests, `e2e/` directory |
+| 26 | **Test coverage measurement** | Coverage tracking so the agent knows if new code is tested | `.codecov.yml`, `coverageThreshold` in jest config, `--cov` in pytest, `cover` profile in Go |
+| 27 | **CI pipeline** | Automated checks on every push or PR | `.github/workflows/ci.yml`, `.circleci/config.yml`, `.gitlab-ci.yml`, `Jenkinsfile` |
+| 28 | **Fast CI feedback** | CI completes quickly enough for agent iteration | CI workflow with documented expected duration, parallel jobs, test splitting |
+| 29 | **Test run documentation** | Agent knows exactly how to run which tests | Test commands in README, AGENTS.md, CONTRIBUTING.md, or Makefile help target |
+| 30 | **Config/schema validation** | YAML, JSON, config files validated automatically | `yamllint` config, JSON schema `$schema` refs, `actionlint` in CI, `taplo` for TOML |
+| 31 | **Snapshot or golden-file tests** | Tests that detect unexpected output changes | `__snapshots__/` directories, `.snap` files, `testdata/` golden files, VCR cassettes |
+| 32 | **Benchmark suite** | Performance tests the agent can run to check for regressions | `bench/`, `benchmarks/`, `*_bench_test.go`, pytest-benchmark, Criterion.rs |
+| 33 | **Warnings-as-errors** | Compiler/runtime warnings treated as failures | `-Werror`, `warningsAsErrors` in build config, `filterwarnings = error` in pytest |
+| 34 | **Spell/typo checking** | Automated spelling checks in CI or hooks | `.cspell.json`, `codespell` in pre-commit, `typos.toml`, spell check CI step |
+
+---
+
+## Pillar 3 · Workflows & Automation
+
+The processes that support agent-driven development — how work is structured,
+tracked, and shipped.
+
+| # | Feature | What to look for | Evidence |
+|---|---------|------------------|----------|
+| 35 | **Issue templates** | Structured templates for bug reports, feature requests | `.github/ISSUE_TEMPLATE/` with `bug_report.md`, `feature_request.md`, `config.yml` |
+| 36 | **PR template** | Template that guides PR descriptions | `.github/pull_request_template.md`, PR template with checklist items |
+| 37 | **Dependency update automation** | Automated PRs for dependency updates | `.github/dependabot.yml`, `renovate.json`, `.renovaterc`, Renovate preset configs |
+| 38 | **Release automation** | Automated release pipeline (build, tag, publish) | Release workflow in CI, `semantic-release` config, GoReleaser config, `release-please` |
+| 39 | **Branch protection** | Protected main branch with required checks | Branch protection rules (inferred from merge queue config, required status checks in CI) |
+| 40 | **Merge automation** | Merge queue, auto-merge, or merge bot | `merge_group` trigger in CI, Mergify config, auto-merge labels, `gh pr merge --auto` |
+| 41 | **Task runner** | Single entry point for common commands | `Makefile`, `Justfile`, `Taskfile.yml`, `package.json` scripts section, `Rakefile` |
+| 42 | **Structured change tracking** | Changesets, conventional commits, or similar discipline | `.changeset/` directory, `commitlint` config, conventional commit enforcement in CI |
+| 43 | **CI concurrency control** | Cancel-in-progress, concurrency groups to avoid CI pile-up | `concurrency:` blocks in GitHub Actions, `cancel-in-progress: true` |
+| 44 | **Automated release notes** | Changelog/release notes generated from commits or PRs | `release-please` config, `auto-changelog`, `git-cliff`, `conventional-changelog` |
+| 45 | **Stale issue/PR management** | Automation to close or label stale items | `.github/workflows/stale.yml`, `stale` bot config, issue lifecycle labels |
+| 46 | **Label automation** | Automatic PR/issue labeling based on paths or content | `.github/labeler.yml`, label-sync config, auto-label workflows |
+| 47 | **Multi-platform CI** | CI matrix covering multiple OS, arch, or runtime versions | `matrix:` in CI with `os: [ubuntu, macos, windows]` or multiple language versions |
+| 48 | **Deployment automation** | Automated deployment pipeline | Deploy workflow triggered on merge/tag, staging + production environments in CI |
+| 49 | **Automated code review checks** | Bot-driven review checks beyond CI | Danger.js config, review bot config, required review assignments, CODEOWNERS + required reviews |
+
+---
+
+## Pillar 4 · Policy & Governance
+
+Rules, ownership, and constraints the agent must know about and respect.
+
+| # | Feature | What to look for | Evidence |
+|---|---------|------------------|----------|
+| 50 | **Comprehensive .gitignore** | Covers secrets, build artifacts, IDE files, agent artifacts | `.gitignore` with entries for `.env`, `node_modules/`, build dirs, `.cursor/`, `.claude/` |
+| 51 | **License** | Clear license at root | `LICENSE`, `MIT-LICENSE`, `COPYING`, `LICENSE.md` |
+| 52 | **Code ownership** | File/directory ownership mapping | `CODEOWNERS`, `.github/CODEOWNERS`, docs describing area owners or maintainer teams |
+| 53 | **Security policy** | How to report vulnerabilities | `SECURITY.md`, `.github/security.md`, security reporting instructions |
+| 54 | **Code of conduct** | Community standards | `CODE_OF_CONDUCT.md`, conduct link in contributing guide |
+| 55 | **AI usage policy** | Documented guidelines for AI/agent contributions | AI policy in AGENTS.md, CONTRIBUTING.md, or standalone doc; agent boundary definitions |
+| 56 | **Secrets management** | Secrets handled via environment/vault, not hardcoded | References to `${{ secrets.* }}` in CI, vault config, `.env.example` without values, `git-secrets` |
+| 57 | **Security scanning** | Automated vulnerability scanning in CI | `.github/workflows/codeql.yml`, Snyk config, `gosec` in CI, Trivy, Dependabot security alerts |
+| 58 | **Git attributes** | Line endings, diff drivers, LFS, linguist overrides | `.gitattributes` with `text=auto`, `linguist-generated`, LFS tracking patterns |
+| 59 | **Contributor agreement** | DCO sign-off or CLA process | DCO bot config, `Signed-off-by` requirement in contributing guide, CLA-assistant config |
+| 60 | **Governance model** | Documented maintainer roles, decision-making process | `GOVERNANCE.md`, `MAINTAINERS.md`, governance section in docs, team/role descriptions |
+| 61 | **CI workflow validation** | CI config itself is linted/validated | `actionlint` step in CI, `circleci config validate`, CI config schema validation |
+| 62 | **Environment separation** | Distinct configs for dev/test/prod | `.env.test`, `.env.production`, environment-specific config directories, config per deploy target |
+
+---
+
+## Pillar 5 · Build & Dev Environment
+
+Can the agent actually build, run, and iterate on the project?  Reproducibility
+and speed matter — an agent that can't build the project can't do anything.
+
+| # | Feature | What to look for | Evidence |
+|---|---------|------------------|----------|
+| 63 | **Dependency lockfile** | Pinned dependency versions for reproducible installs | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `uv.lock`, `Cargo.lock`, `go.sum`, `Gemfile.lock`, `poetry.lock` |
+| 64 | **Single-command build** | One documented command to build the entire project | `make build`, `npm run build`, `cargo build` documented in README or agent file |
+| 65 | **Single-command dev setup** | One command to bootstrap a working dev environment | `bin/setup`, `make dev`, `scripts/bootstrap.sh`, `just setup` |
+| 66 | **Dev container** | Containerized dev environment definition | `.devcontainer/devcontainer.json`, `devcontainer.json` at root |
+| 67 | **Containerized services** | Docker-based local development stack | `Dockerfile`, `docker-compose.yml`, `compose.yaml` with dev services |
+| 68 | **Reproducible environment** | Declarative, reproducible dev environment | `flake.nix`, `shell.nix`, `devbox.json`, hermetic build definitions |
+| 69 | **Tool version pinning** | Runtime/tool versions pinned to a file | `.tool-versions`, `mise.toml`, `.node-version`, `.python-version`, `.ruby-version`, `rust-toolchain.toml` |
+| 70 | **Monorepo orchestration** | Tooling for multi-package repositories | Workspace config in `package.json`, `pnpm-workspace.yaml`, Cargo workspace, Go multi-module, Nx/Turborepo/Bazel config |
+| 71 | **Build caching** | Caching for faster rebuilds | CI cache steps (`actions/cache`), Turborepo remote cache, ccache/sccache config, layer caching in Docker |
+| 72 | **Cross-platform support** | Builds on multiple OS/arch | CI matrix with multiple OS entries, cross-compilation configs, multi-arch Docker builds |
+| 73 | **Cloud dev environment** | Cloud-based workspace configuration | `.devcontainer/` with Codespaces features, `.gitpod.yml`, cloud workspace config |
+| 74 | **Package manager configuration** | Custom registry, auth, resolution settings | `.npmrc`, `pip.conf`, `.cargo/config.toml`, registry overrides, resolution overrides |
+
+---
+
+## Summary
+
+| Pillar | Features | What it answers |
+|--------|----------|-----------------|
+| Agent Instructions | 18 | Does the agent know what to do? |
+| Feedback Loops | 16 | Does the agent know if it's right? |
+| Workflows & Automation | 15 | Does the process support agent work? |
+| Policy & Governance | 13 | Does the agent know the rules? |
+| Build & Dev Environment | 12 | Can the agent build and run the project? |
+| **Total** | **74** | |

package/plugins/onboarding/skills/agent-readiness-report/README.md

@@ -0,0 +1,23 @@
+# Agent Readiness Report
+
+Evaluate how well a repository supports autonomous AI-assisted development.
+
+## Triggers
+
+This skill is activated by the following keywords:
+
+- `agent-readiness-report`
+
+## What This Does
+
+Assesses a codebase across five pillars that determine whether an AI agent can work effectively in a repository. Produces a structured report identifying what's present, what's missing, and which pillars are strongest and weakest.
+
+The five pillars are:
+
+- **Agent Instructions** — does the agent know what to do?
+- **Feedback Loops** — does the agent know if it's right?
+- **Workflows & Automation** — does the process support agent work?
+- **Policy & Governance** — does the agent know the rules?
+- **Build & Dev Environment** — can the agent build and run the project?
+
+Once you have a report, use `improve-agent-readiness` to turn the gaps into concrete fixes.