From d74934f2e5f897955b5adc3e48cb1d1591296e0d Mon Sep 17 00:00:00 2001 From: robolearning123 Date: Sat, 28 Feb 2026 22:48:00 -0500 Subject: [PATCH 1/3] feat: add CLAUDE.md, copilot-instructions, copilot-setup-steps, .gitattributes Add agent guidance files for all major AI coding tools: - CLAUDE.md at repo root (imports AGENTS.md) - .github/copilot-instructions.md for GitHub Copilot - .github/workflows/copilot-setup-steps.yml for Copilot coding agent - .gitattributes for cross-platform line ending normalization - Update AGENTS.md to reflect v0.1.0 and new provider architecture Co-Authored-By: Claude Opus 4.6 --- .gitattributes | 16 ++++++ .github/copilot-instructions.md | 11 +++++ .github/workflows/copilot-setup-steps.yml | 18 +++++++ AGENTS.md | 59 +++++++++-------------- CLAUDE.md | 57 ++++++++++++++++++++++ 5 files changed, 125 insertions(+), 36 deletions(-) create mode 100644 .gitattributes create mode 100644 .github/copilot-instructions.md create mode 100644 .github/workflows/copilot-setup-steps.yml create mode 100644 CLAUDE.md diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..db6a1d3 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,16 @@ +# Auto detect text files and normalize line endings +* text=auto + +# Source +*.ts text eol=lf +*.js text eol=lf +*.json text eol=lf +*.yml text eol=lf +*.yaml text eol=lf +*.md text eol=lf + +# Binary +*.png binary +*.jpg binary +*.gif binary +*.ico binary diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..46f7c08 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,11 @@ +TypeScript project using Node 20+ with strict mode enabled. + +Commands: `npm test` (152 tests), `npm run check` (typecheck + lint + format), `npm run build` (tsc). + +Code style: kebab-case files, PascalCase interfaces, camelCase functions. Interfaces over types. Avoid `any`, use `unknown`. Export types from `src/types.ts`. + +Testing: Node built-in test runner via `tsx --test`. Fixtures in `test/fixtures/`. Always run tests after changes and update tests in the same pass as code changes. + +Git: Atomic commits with semantic prefixes (feat/fix/docs/chore). Run `npm run check` before committing. + +Do not add external API calls — all scanning must remain local. Do not modify `src/types.ts` without updating all consumers. diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml new file mode 100644 index 0000000..c6c16b0 --- /dev/null +++ b/.github/workflows/copilot-setup-steps.yml @@ -0,0 +1,18 @@ +name: "Copilot Setup Steps" + +on: + workflow_dispatch: + +jobs: + copilot-setup-steps: + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + - run: npm ci + - run: npm run build diff --git a/AGENTS.md b/AGENTS.md index 934c0d2..89e0511 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,22 +4,24 @@ Instructions for AI agents working with the agent-ready codebase. ## Project Overview -**agent-ready** is a Factory.ai-compatible repository maturity scanner that evaluates codebases against the 9 Pillars / 5 Levels model. +**agent-ready** is a repo infrastructure setup tool for agent-guided development. One command to make any repo agent-ready — everything except the code. -**Version:** 0.0.1 +**Version:** 0.1.0 **Language:** TypeScript **Runtime:** Node.js >= 20 ## Quick Commands ```bash -npm install # Install dependencies -npm run dev -- scan . # Scan current directory -npm test # Run tests (22 tests) -npm run typecheck # Type check -npm run lint # Lint code -npm run format # Format code -npm run build # Build for production +npm install # Install dependencies +npm run dev -- scan . # Scan current directory +npm test # Run tests (152 tests) +npm run test:coverage # Coverage with c8 +npm run typecheck # Type check (tsc --noEmit) +npm run lint # ESLint +npm run format # Prettier +npm run check # All gates: typecheck + lint + format +npm run build # Build for production ``` ## Project Structure @@ -72,33 +74,18 @@ agent-readiness/ ## Key Concepts -### 9 Pillars (Factory.ai Compatible) -| ID | Pillar | Checks | -|----|--------|--------| -| `docs` | Documentation | README, AGENTS.md, CONTRIBUTING, CHANGELOG | -| `style` | Style & Validation | EditorConfig, linters, formatters | -| `build` | Build System | Package manifest, CI/CD, lock files | -| `test` | Testing | Test files, config, integration tests | -| `security` | Security | .gitignore, CODEOWNERS, dependabot | -| `observability` | Observability | Logging, tracing, metrics | -| `env` | Environment | .env.example, devcontainer | -| `task_discovery` | Task Discovery | Issue/PR templates | -| `product` | Product | Feature flags, analytics | - -### 5 Levels -| Level | Name | Threshold | -|-------|------|-----------| -| L1 | Functional | 80% of L1 checks | -| L2 | Documented | 80% of L2 checks | -| L3 | Standardized | 80% of L3 checks | -| L4 | Optimized | 80% of L4 checks | -| L5 | Autonomous | 80% of L5 checks | - -### Gating Rule -Level N achieved when: -1. ALL required checks at level N pass -2. ≥80% of ALL checks at level N pass -3. All previous levels achieved +### 9 Setup Categories (Providers) +| Provider | What It Sets Up | +|----------|----------------| +| Agent Guidance | AGENTS.md, CLAUDE.md, copilot-instructions.md, cursor rules | +| Code Quality | Biome (JS/TS) or Ruff+mypy (Python), .editorconfig | +| Testing | Test scaffold, BDT branch matrix, coverage config | +| CI/CD | ci.yml, claude.yml, copilot-setup-steps.yml | +| Hooks | Lefthook/Husky pre-commit + Claude PostToolUse hooks | +| Branch Ruleset | GitHub rulesets via API (require PR, reviews, status checks) | +| Templates | Issue forms (YAML), PR template, CODEOWNERS, SECURITY.md | +| DevContainer | .devcontainer/devcontainer.json | +| Security | dependabot.yml, push protection, CodeQL | ## Code Conventions diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..92056a8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,57 @@ +# agent-ready + +Repo infrastructure setup tool for agent-guided development. TypeScript, Node 20+, Commander CLI. + +## Commands + +```bash +npm install # install dependencies +npm run dev -- scan . # run CLI in dev mode +npm test # 152 tests, node test runner +npm run test:coverage # coverage with c8 +npm run typecheck # tsc --noEmit +npm run lint # eslint +npm run format # prettier +npm run check # typecheck + lint + format (all gates) +npm run build # tsc → dist/ +``` + +## Architecture + +``` +src/index.ts (CLI entry, commander) + → src/commands/scan.ts → src/scanner.ts (orchestrator) + → src/commands/init.ts (file generation) + +src/scanner.ts + → src/profiles/ (load YAML profile) + → src/engine/context.ts (build scan context, detect project type) + → src/checks/ (execute checks: file-exists, path-glob, dependency-detect, etc.) + → src/engine/level-gate.ts (80% rule, level calculation) + → src/output/ (JSON + markdown formatting) +``` + +## Conventions + +- TypeScript strict mode, interfaces over types, avoid `any` +- Files: `kebab-case.ts`, interfaces: `PascalCase`, functions: `camelCase` +- Check IDs: `pillar.check_name` (e.g., `docs.readme`, `test.framework`) +- Export all types from `src/types.ts` +- Keep checks pure — no external API calls, scanning is local only + +## Testing + +- Runner: `tsx --test` (Node built-in test runner) +- Test files mirror source: `src/checks/file-exists.ts` → `test/checks.test.ts` +- Fixtures in `test/fixtures/` (minimal-repo, standard-repo, l3-repo, monorepo, python-repo, empty-repo) +- Run tests after every change: `npm test` +- Update tests in the same pass as code changes + +## Git + +- Atomic commits, one logical change per commit +- Branch naming: `feat/`, `fix/`, `docs/`, `chore/` +- PR titles: semantic prefix (`feat:`, `fix:`, `docs:`, etc.) +- Run `npm run check` before committing + +@AGENTS.md From eb451ce072caf8947149fe721f0199ad5e9ceb19 Mon Sep 17 00:00:00 2001 From: robolearning123 Date: Sat, 28 Feb 2026 22:48:09 -0500 Subject: [PATCH 2/3] feat: upgrade issue templates from Markdown to YAML forms Replace Markdown issue templates with YAML issue forms for structured input. YAML forms are easier for agents to parse and provide dropdowns, required field validation, and better UX. - bug_report.yml: structured fields with OS dropdown, version inputs - feature_request.yml: category dropdown, structured problem/solution - config.yml: disable blank issues, link to discussions - Remove old bug_report.md and feature_request.md Co-Authored-By: Claude Opus 4.6 --- .github/ISSUE_TEMPLATE/bug_report.md | 38 ------------ .github/ISSUE_TEMPLATE/bug_report.yml | 67 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/feature_request.md | 30 ---------- .github/ISSUE_TEMPLATE/feature_request.yml | 43 ++++++++++++++ 5 files changed, 115 insertions(+), 68 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml delete mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 39394e0..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: Bug Report -about: Create a report to help us improve -title: '[BUG] ' -labels: bug -assignees: '' ---- - -## Description - -A clear and concise description of what the bug is. - -## Steps to Reproduce - -1. Run `agent-ready scan ...` -2. See error - -## Expected Behavior - -A clear and concise description of what you expected to happen. - -## Actual Behavior - -What actually happened instead. - -## Screenshots / Output - -If applicable, add screenshots or command output to help explain your problem. - -## Environment - -- OS: [e.g., macOS 14.0, Windows 11, Ubuntu 22.04] -- Node.js version: [e.g., 20.10.0] -- agent-ready version: [e.g., 0.1.0] - -## Additional Context - -Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..08e25d1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,67 @@ +name: Bug Report +description: Report a bug with agent-ready +labels: [bug] +body: + - type: textarea + id: description + attributes: + label: Description + description: What happened? + placeholder: A clear description of the bug + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to Reproduce + description: How can we reproduce this? + value: | + 1. Run `agent-ready scan ...` + 2. + 3. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What should have happened? + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What happened instead? + validations: + required: true + - type: input + id: version + attributes: + label: agent-ready version + placeholder: "0.1.0" + validations: + required: true + - type: input + id: node-version + attributes: + label: Node.js version + placeholder: "20.10.0" + validations: + required: true + - type: dropdown + id: os + attributes: + label: Operating System + options: + - macOS + - Linux + - Windows + validations: + required: true + - type: textarea + id: output + attributes: + label: Command Output + description: Paste the full command output if relevant + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..1ae9065 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Discussions + url: https://github.com/agent-next/agent-ready/discussions + about: Ask questions and share ideas diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index 20bfa5e..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -name: Feature Request -about: Suggest an idea for this project -title: '[FEATURE] ' -labels: enhancement -assignees: '' ---- - -## Problem Statement - -Is your feature request related to a problem? Please describe. -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -## Proposed Solution - -Describe the solution you'd like. -A clear and concise description of what you want to happen. - -## Alternatives Considered - -Describe alternatives you've considered. -A clear and concise description of any alternative solutions or features you've considered. - -## Additional Context - -Add any other context, mockups, or screenshots about the feature request here. - -## Implementation Notes - -If you have ideas about how this could be implemented, share them here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..926c9dd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,43 @@ +name: Feature Request +description: Suggest a new feature or improvement +labels: [enhancement] +body: + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem does this solve? + placeholder: "I'm always frustrated when..." + validations: + required: true + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: What should agent-ready do? + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Any other approaches you've thought about? + - type: dropdown + id: category + attributes: + label: Category + options: + - New provider + - Existing provider improvement + - CLI UX + - GitHub Action + - MCP server + - Documentation + - Other + validations: + required: true + - type: textarea + id: context + attributes: + label: Additional Context + description: Screenshots, mockups, or any other context From 45a498e4cd96397da10953e5ebb4cc9b99ce2684 Mon Sep 17 00:00:00 2001 From: robolearning123 Date: Sat, 28 Feb 2026 22:48:17 -0500 Subject: [PATCH 3/3] docs: add v2 pivot design document Design for pivoting agent-ready from repo maturity scanner to repo infrastructure setup tool. 9 modular providers, CLI + Action, autonomous operation with opinionated defaults. Co-Authored-By: Claude Opus 4.6 --- docs/plans/2026-02-28-pivot-design.md | 469 ++++++++++++++++++++++++++ 1 file changed, 469 insertions(+) create mode 100644 docs/plans/2026-02-28-pivot-design.md diff --git a/docs/plans/2026-02-28-pivot-design.md b/docs/plans/2026-02-28-pivot-design.md new file mode 100644 index 0000000..fa22526 --- /dev/null +++ b/docs/plans/2026-02-28-pivot-design.md @@ -0,0 +1,469 @@ +# Agent-Ready v2: Pivot Design + +## Summary + +Pivot agent-ready from a passive repo maturity scanner to an active repo infrastructure setup tool for agent-guided development. One command sets up everything an agent needs before writing code. Idempotent — first run does full setup, subsequent runs fill gaps. + +**From**: "Factory-compatible repo maturity scanner" (score repos L1-L5) +**To**: "Everything except the code" (set up all repo infra for agents) + +## Product Identity + +- **Package**: `agent-ready` (keep npm, GitHub Action, Marketplace identity) +- **Description**: "Everything except the code — one command to make any repo agent-ready" +- **Commands**: + - `agent-ready setup .` — detect project type, generate all infra, configure GitHub + - `agent-ready check .` — verify setup completeness, JSON output for agent pre-flight +- **Distribution**: CLI (`npx`), GitHub Action, MCP server +- **Interaction**: Fully autonomous, opinionated defaults, override via flags or `.agent-ready.yml` +- **Languages**: JS/TS + Python at launch + +## Architecture: Modular Providers + +``` +CLI (setup/check) + ↓ +SetupEngine + ├─ detect project type (reuse src/engine/project-type.ts) + ├─ build context (reuse src/engine/context.ts) + ├─ run providers in order: + │ + ├─ 1. AgentGuidanceProvider + ├─ 2. CodeQualityProvider + ├─ 3. TestingProvider + ├─ 4. CIProvider + ├─ 5. HooksProvider + ├─ 6. BranchRulesetProvider + ├─ 7. TemplatesProvider + ├─ 8. DevContainerProvider + ├─ 9. SecurityProvider + │ + └─ output results (JSON envelope) +``` + +### Provider Interface + +Every provider implements: + +```typescript +interface Provider { + name: string; + detect(ctx: ScanContext): Promise; // what exists + plan(ctx: ScanContext, state: ProviderState): Promise; // what's missing + apply(ctx: ScanContext, actions: Action[]): Promise; // create/configure + verify(ctx: ScanContext): Promise; // confirm it worked +} + +interface Action { + type: 'create_file' | 'modify_file' | 'api_call' | 'install_dep' | 'run_command'; + target: string; // file path or API endpoint + description: string; // human-readable + content?: string; // file content or API payload +} + +interface Result { + action: Action; + status: 'applied' | 'skipped' | 'failed'; + reason?: string; +} +``` + +### Output Format + +JSON envelope (consistent with pm-sim pattern): + +```json +{ + "ok": true, + "data": { + "project_type": "webapp", + "language": "typescript", + "applied": [ + {"provider": "agent_guidance", "action": "create_file", "target": "AGENTS.md"}, + {"provider": "ci", "action": "create_file", "target": ".github/workflows/ci.yml"} + ], + "skipped": [ + {"provider": "code_quality", "action": "create_file", "target": "biome.json", "reason": "eslint.config.js already exists"} + ], + "failed": [], + "summary": "9 applied, 2 skipped, 0 failed" + } +} +``` + +## Provider Specifications + +### 1. AgentGuidanceProvider + +**Purpose**: Generate all agent instruction files tailored to the detected project. + +**Detects**: Existing AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/, .github/instructions/*.instructions.md + +**Generates** (if missing): + +| File | Content Source | +|------|---------------| +| `AGENTS.md` | Analyzes project structure, package.json/pyproject.toml, test commands, build commands. Generates 6 sections: commands, testing, project structure, code style, git workflow, boundaries. Cross-tool standard. | +| `CLAUDE.md` | Imports AGENTS.md via `@AGENTS.md`, adds Claude-specific hooks config reference. | +| `.github/copilot-instructions.md` | Concise subset of AGENTS.md for Copilot. Max 2 pages. | +| `.github/instructions/*.instructions.md` | Path-scoped instructions with YAML frontmatter `applyTo` globs. One per major directory (src/, tests/, etc.) | +| `.cursor/rules/project.mdc` | Cursor project rules derived from AGENTS.md. | + +**Idempotent behavior**: If file exists, skip. Never overwrite user content. + +### 2. CodeQualityProvider + +**Purpose**: Install and configure linters, formatters, type checkers. + +**Detection logic**: + +| Language | Detect Via | Install | +|----------|-----------|---------| +| TypeScript | `tsconfig.json` | Biome (lint+format). If ESLint already exists, skip. | +| JavaScript | `package.json` without tsconfig | Biome (lint+format) | +| Python | `pyproject.toml` or `setup.py` | Ruff (lint+format) + mypy (types) | + +**Generates**: + +| File | When | +|------|------| +| `biome.json` | JS/TS project, no existing ESLint | +| `pyproject.toml [tool.ruff]` section | Python project, no existing ruff config | +| `pyproject.toml [tool.mypy]` section | Python project, no existing mypy config | +| `.editorconfig` | Always if missing | + +**Installs** (via npm/pip): +- JS/TS: `@biomejs/biome` as devDependency +- Python: `ruff`, `mypy` as dev dependencies (via `uv add --dev` or `pip install`) + +### 3. TestingProvider + +**Purpose**: Scaffold test infrastructure and BDT methodology. + +**Detection**: Existing test directories, test config files, coverage config. + +**Generates**: + +| Item | JS/TS | Python | +|------|-------|--------| +| Test runner config | `vitest.config.ts` (or detect existing jest/mocha) | `pyproject.toml [tool.pytest]` | +| Directory structure | `tests/unit/`, `tests/integration/`, `tests/e2e/` | `tests/unit/`, `tests/integration/`, `tests/e2e/` | +| Coverage config | vitest coverage settings | `pytest-cov` config | +| BDT template | `tests/BRANCH_MATRIX.md` | `tests/BRANCH_MATRIX.md` | +| Conftest/setup | `tests/setup.ts` | `tests/conftest.py` | + +**BDT integration**: Copies branch matrix template from existing `skill/agent-ready/references/testing/branch-matrices.md` into the project. This is agent-ready's differentiator — no other setup tool includes a testing methodology. + +### 4. CIProvider + +**Purpose**: Generate GitHub Actions workflows. + +**Generates**: + +| Workflow | Purpose | Trigger | +|----------|---------|---------| +| `.github/workflows/ci.yml` | lint + typecheck + test + build | push, pull_request | +| `.github/workflows/claude.yml` | Claude Code Action (PR review + @claude mentions) | issue_comment, pull_request | +| `.github/workflows/copilot-setup-steps.yml` | Copilot coding agent environment setup | workflow_dispatch, push, pull_request | + +**CI workflow** is language-aware: +- JS/TS: setup-node, npm ci, biome check, tsc --noEmit, vitest, build +- Python: setup-python, uv install, ruff check, mypy, pytest + +**Claude workflow** uses `anthropics/claude-code-action@v1` with sensible defaults. + +**Copilot setup steps** installs project dependencies so Copilot coding agent can work. + +### 5. HooksProvider + +**Purpose**: Set up pre-commit hooks (git) and Claude Code hooks. + +**Detection**: Existing .husky/, lefthook.yml, .pre-commit-config.yaml, .claude/settings.json + +**Strategy**: +- JS/TS: Lefthook (faster than Husky, parallel execution). Falls back to Husky if already installed. +- Python: Lefthook (no Node dependency needed) or pre-commit framework if already present. + +**Generates**: + +| File | Content | +|------|---------| +| `lefthook.yml` | pre-commit: lint + format + typecheck on staged files | +| `.claude/settings.json` | PostToolUse hook: run tests after Edit/Write | + +**Git hooks** gate commits. **Claude hooks** gate every edit. Both needed. + +### 6. BranchRulesetProvider + +**Purpose**: Configure GitHub branch rulesets via REST API. + +**Uses rulesets** (not legacy branch protection rules). Rulesets are the current GitHub standard. + +**Rules applied to `main`/`master`**: + +| Rule | Purpose | +|------|---------| +| `pull_request` | Require PR, 1 approval, dismiss stale reviews, resolve threads | +| `required_status_checks` | CI must pass before merge | +| `deletion` | Prevent branch deletion | +| `non_fast_forward` | Prevent force push | + +**Implementation**: `gh api repos/{owner}/{repo}/rulesets --method POST --input -` + +**Fallback**: If `gh` CLI not available or insufficient permissions, output the `gh api` command for manual execution. + +### 7. TemplatesProvider + +**Purpose**: Generate GitHub repo templates. + +**Generates** (if missing): + +| File | Format | +|------|--------| +| `.github/ISSUE_TEMPLATE/bug_report.yml` | YAML issue form (not Markdown template — structured fields are easier for agents) | +| `.github/ISSUE_TEMPLATE/feature_request.yml` | YAML issue form | +| `.github/ISSUE_TEMPLATE/config.yml` | Template chooser config | +| `.github/PULL_REQUEST_TEMPLATE.md` | PR template with checklist | +| `.github/CODEOWNERS` | Default: `* @{repo-owner}` | +| `.gitignore` | Language-appropriate (gitignore.io patterns) | +| `.gitattributes` | Line ending normalization | +| `CONTRIBUTING.md` | Standard contributing guide | +| `SECURITY.md` | Vulnerability disclosure policy | +| `LICENSE` | MIT (default, configurable) | + +### 8. DevContainerProvider + +**Purpose**: Generate devcontainer config for reproducible agent environments. + +**Generates**: + +| File | Content | +|------|---------| +| `.devcontainer/devcontainer.json` | Language-appropriate base image, extensions, postCreateCommand | + +**JS/TS container**: Node 20, Biome extension, GitHub CLI +**Python container**: Python 3.12, Ruff extension, GitHub CLI + +### 9. SecurityProvider + +**Purpose**: Enable GitHub security features. + +**Generates**: + +| Item | Method | +|------|--------| +| `.github/dependabot.yml` | Create file — grouped updates, weekly schedule | +| Secret scanning + push protection | `gh api` — enable on repo (free for public repos) | +| CodeQL default setup | `gh api` — enable default setup (auto-detects languages) | + +**Fallback**: If API calls fail (permissions), output commands for manual execution. + +## What Gets Deleted + +| Current Module | Reason | +|----------------|--------| +| `profiles/factory_compat.yaml` (2393 lines) | Scoring framework no longer needed | +| `src/engine/level-gate.ts` | L1-L5 levels removed | +| `src/scanner.ts` | Replaced by SetupEngine | +| `src/commands/scan.ts` | Replaced by setup/check commands | +| `src/output/markdown.ts` | Replaced by JSON envelope + simple CLI output | +| `src/profiles/` | No more profile loading | +| `skill/agent-ready/references/levels.md` | Levels removed | +| `skill/agent-ready/references/scoring-rubric.md` | Scoring removed | +| `skill/agent-ready/references/analysis-patterns.md` | Analysis patterns removed | + +## What Gets Kept (and refactored) + +| Current Module | Reuse | +|----------------|-------| +| `src/engine/project-type.ts` | Direct reuse — project type detection is the foundation | +| `src/engine/context.ts` | Direct reuse — scan context, monorepo detection | +| `src/checks/` (11 check types) | Reuse as primitives inside providers for detect/verify | +| `src/utils/` (fs, git, exec, yaml) | Direct reuse | +| `src/i18n/` | Direct reuse | +| `src/types.ts` | Refactor — remove Level/Pillar types, add Provider types | +| `test/fixtures/` | Keep and extend | +| `packages/mcp/` | Rebuild tools around setup/check | +| `skill/agent-ready/references/testing/` | Keep BDT references (1911 lines, just merged) | +| `action.yml` | Refactor inputs (mode: setup/check instead of fail-below-level) | +| `package.json` | Keep identity, update scripts | + +## New Directory Structure + +``` +agent-ready/ +├── src/ +│ ├── index.ts # CLI entry (commander) +│ ├── lib.ts # Public API exports +│ ├── types.ts # Provider, Action, Result types +│ ├── commands/ +│ │ ├── setup.ts # setup command +│ │ └── check.ts # check command +│ ├── engine/ +│ │ ├── setup-engine.ts # Orchestrator: runs providers in order +│ │ ├── context.ts # (kept) Scan context builder +│ │ ├── project-type.ts # (kept) Project type detection +│ │ └── index.ts +│ ├── providers/ +│ │ ├── index.ts # Provider registry +│ │ ├── agent-guidance.ts # AGENTS.md, CLAUDE.md, copilot-instructions, cursor rules +│ │ ├── code-quality.ts # Biome/Ruff, mypy/tsc, editorconfig +│ │ ├── testing.ts # Test scaffold, BDT, coverage config +│ │ ├── ci.ts # GitHub Actions workflows +│ │ ├── hooks.ts # Lefthook/Husky + Claude hooks +│ │ ├── branch-ruleset.ts # GitHub rulesets via API +│ │ ├── templates.ts # Issue forms, PR template, CODEOWNERS, etc. +│ │ ├── devcontainer.ts # .devcontainer/devcontainer.json +│ │ └── security.ts # Dependabot, secret scanning, CodeQL +│ ├── checks/ # (kept) Check primitives +│ ├── i18n/ # (kept) Internationalization +│ └── utils/ # (kept) FS, git, exec, yaml +├── templates/ # File templates (Mustache/Handlebars) +│ ├── agents-md/ # AGENTS.md templates per project type +│ ├── claude-md/ # CLAUDE.md templates +│ ├── ci/ # Workflow templates +│ ├── hooks/ # lefthook.yml, .claude/settings.json +│ ├── testing/ # Test scaffolds, BDT branch matrix +│ ├── devcontainer/ # devcontainer.json templates +│ ├── github/ # Issue forms, PR template, CODEOWNERS +│ └── security/ # dependabot.yml, SECURITY.md +├── packages/ +│ ├── mcp/ # MCP server (rebuilt) +│ │ └── src/tools/ +│ │ ├── setup.ts # agent_ready_setup tool +│ │ └── check.ts # agent_ready_check tool +│ └── plugin/ # Claude plugin (rebuilt) +├── skill/ +│ └── agent-ready/ +│ ├── SKILL.md # Updated for setup/check flow +│ └── references/ +│ └── testing/ # (kept) BDT reference docs +├── test/ +│ ├── providers/ # One test file per provider +│ ├── engine.test.ts +│ ├── e2e/ +│ └── fixtures/ # (kept + extended) +├── action.yml # GitHub Action (refactored) +├── package.json +└── README.md # Rewritten +``` + +## CLI UX + +```bash +# Full setup (autonomous, opinionated) +$ npx agent-ready setup . + +agent-ready v2.0.0 +Detected: TypeScript webapp (Next.js) + + [+] AGENTS.md created + [+] CLAUDE.md created + [+] .github/copilot-instructions.md created + [+] .github/instructions/src.md created + [+] biome.json created + [=] eslint.config.js skipped (exists) + [+] .editorconfig created + [+] tests/unit/ created + [+] tests/BRANCH_MATRIX.md created + [+] .github/workflows/ci.yml created + [+] .github/workflows/claude.yml created + [+] .github/workflows/copilot-setup-steps.yml created + [+] lefthook.yml created + [+] .claude/settings.json created + [+] branch ruleset "main-protection" applied via API + [+] .github/ISSUE_TEMPLATE/bug.yml created + [+] .github/PULL_REQUEST_TEMPLATE.md created + [+] .github/CODEOWNERS created + [+] .devcontainer/devcontainer.json created + [+] .github/dependabot.yml created + [+] push protection enabled via API + [!] CodeQL default setup failed (needs admin access) + +21 applied, 1 skipped, 1 failed + +# Verify (agent pre-flight) +$ npx agent-ready check . +{"ok": true, "data": {"complete": true, "missing": ["codeql"], ...}} + +# Override defaults +$ npx agent-ready setup . --no-devcontainer --hook-framework=husky +``` + +## GitHub Action (refactored) + +```yaml +name: Agent Ready +on: [push, pull_request] +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: agent-next/agent-ready@v2 + with: + mode: check # or 'setup' for CI-driven setup + fail-on-missing: true +``` + +## MCP Server Tools (rebuilt) + +| Tool | Purpose | +|------|---------| +| `agent_ready_setup` | Run full setup on a repo path | +| `agent_ready_check` | Pre-flight check, return JSON status | + +## Config File (optional override) + +```yaml +# .agent-ready.yml +devcontainer: false +hook_framework: husky # default: lefthook +license: Apache-2.0 # default: MIT +skip_providers: + - branch_ruleset # skip if no gh CLI +extra_codeowners: + "src/api/**": "@backend-team" +``` + +## Migration Path + +1. v0.1.0 (current) remains on npm as-is +2. v2.0.0 ships with new setup/check commands +3. `scan` command removed (breaking change, hence major version) +4. GitHub Action inputs change (mode replaces fail-below-level) +5. Marketplace listing updated + +## Build Sequence + +Phase 1 — Core engine + 3 providers: +1. Provider interface + types +2. SetupEngine orchestrator +3. AgentGuidanceProvider (AGENTS.md, CLAUDE.md, copilot-instructions) +4. CodeQualityProvider (Biome/Ruff) +5. TestingProvider (scaffold + BDT) +6. `setup` and `check` CLI commands +7. Tests for all above + +Phase 2 — Remaining providers: +8. CIProvider (workflows) +9. HooksProvider (lefthook + claude hooks) +10. TemplatesProvider (issue forms, PR template, CODEOWNERS) +11. SecurityProvider (dependabot.yml) +12. DevContainerProvider +13. Tests for all above + +Phase 3 — API + distribution: +14. BranchRulesetProvider (gh api calls) +15. MCP server rebuild +16. GitHub Action refactor +17. README rewrite +18. npm publish v2.0.0 + +## Success Criteria + +- `npx agent-ready setup .` on a bare repo produces a fully configured project in < 10 seconds +- `npx agent-ready check .` returns valid JSON that an agent can parse for pre-flight +- Idempotent: running setup twice produces no changes on second run +- Every provider has unit tests with fixture repos +- BDT branch matrix is included in every project's test scaffold