
Readiness Report
- 38 installs
- 33 repo stars
- Updated July 27, 2026
- dirnbauer/webconsulting-skills
Assesses how agent-ready a repository is across five pillars and produces a structured report of gaps and strengths.
About
Evaluates how well a codebase supports autonomous AI-assisted development across five pillars covering 74 features. A developer uses it to assess and report on how agent-ready a repository is.
- Scores a repo across five pillars, 74 features
- Structured report of what is present or missing
Readiness Report by the numbers
- 38 all-time installs (skills.sh)
- Ranked #8,450 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Jul 29, 2026 (Skillselion catalog sync)
npx skills add https://github.com/dirnbauer/webconsulting-skills --skill readiness-reportAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 38 |
|---|---|
| repo stars | ★ 33 |
| Last updated | July 27, 2026 |
| Repository | dirnbauer/webconsulting-skills ↗ |
What it does
Assesses how agent-ready a repository is across five pillars and produces a structured report of gaps and strengths.
Files
Agent Readiness Report
Evaluate how well a repository supports autonomous AI-assisted development.
What this does
Assess a codebase across five pillars that determine whether an AI agent can work effectively in a repository. The output is a structured report identifying what's present and what's missing.
Five Pillars
| Pillar | Question | Features |
|---|---|---|
| Agent Instructions | Does the agent know what to do? | 18 |
| Feedback Loops | Does the agent know if it's right? | 16 |
| Workflows & Automation | Does the process support agent work? | 15 |
| Policy & Governance | Does the agent know the rules? | 13 |
| Build & Dev Environment | Can the agent build and run the project? | 12 |
74 features total. See references/criteria.md for the full list with descriptions and evidence examples.
How to run
Step 1: Run the scanner scripts
Five shell scripts gather filesystem signals — file existence, config patterns, directory structures. They surface what's present so you don't have to run dozens of find commands manually.
bash scripts/scan_agent_instructions.sh /path/to/repo
bash scripts/scan_feedback_loops.sh /path/to/repo
bash scripts/scan_workflows.sh /path/to/repo
bash scripts/scan_policy.sh /path/to/repo
bash scripts/scan_build_env.sh /path/to/repoOr scan all five at once:
for s in scripts/scan_*.sh; do bash "$s" /path/to/repo; echo; doneImportant: The scripts are helpers, not scorers. They find files and patterns but do not evaluate quality. Many features require judgment that only reading the actual files can provide — for example, whether a README includes real build commands or just badges, whether inline documentation is systematic or scattered, whether an AI usage policy has meaningful boundaries.
Step 2: Evaluate each feature
Walk through references/criteria.md pillar by pillar. For each feature:
1. Check the scanner output for relevant signals 2. For features the scanner can't fully evaluate, inspect the files yourself 3. Mark each feature: ✓ (present), ✗ (missing), or — (not applicable)
Features that require judgment (not fully covered by scanners):
- Does the README actually contain build/run/test commands? (not just that it exists)
- Is inline documentation systematic across the public API?
- Are examples actually runnable?
- Does the contributing guide include code standards?
- Is there a meaningful AI usage policy?
- Is the architecture documentation current?
- Are tests documented well enough for an agent to run them?
Step 3: Write the report
Structure the output as:
# Agent Readiness Report: {repo name}
## Summary
- Features present: X / 74
- Strongest pillar: {pillar}
- Weakest pillar: {pillar}
## Pillar 1 · Agent Instructions (X / 18)
✓ Agent instruction file — AGENTS.md at root
✓ AI IDE configuration — .cursor/rules/ with 3 rule files
✗ Multi-model support — only Cursor configured
...
## Pillar 2 · Feedback Loops (X / 16)
...
## Pillar 3 · Workflows & Automation (X / 15)
...
## Pillar 4 · Policy & Governance (X / 13)
...
## Pillar 5 · Build & Dev Environment (X / 12)
...
For each passing feature, briefly note what evidence you found. For each failing feature, note what's missing.
What makes these features useful
Every feature answers: if this is missing, what goes wrong for the AI agent? Features like "agent instruction file" and "tool server configuration" exist because agents need them. Features like "linter" and "CI pipeline" exist because agents need fast, clear feedback on whether their changes are correct — not because they're general best practices.
The criteria were derived from analysis of 123 real repositories across five AI-readiness categories, then filtered for features that actually affect agent effectiveness.
---
Credits & Attribution
This skill is based on the excellent work by [OpenHands](https://github.com/OpenHands/skills).
Original repository: https://github.com/OpenHands/skills
Special thanks to OpenHands for their generous open-source contributions, which helped shape this skill collection. Adapted by webconsulting.at for this skill collection
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.
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 |
#!/usr/bin/env bash
# Scan for Agent Instructions signals (Pillar 1)
# Helps the agent find relevant files — not a substitute for judgment.
REPO="${1:-.}"
cd "$REPO" 2>/dev/null || { echo "Cannot access $REPO"; exit 1; }
echo "=== Pillar 1: Agent Instructions ==="
echo ""
echo "-- Agent instruction files --"
find . -maxdepth 3 -iname 'AGENTS.md' -o -iname 'CLAUDE.md' -o -iname 'COPILOT.md' \
-o -iname 'CONVENTIONS.md' -o -iname 'CODING_GUIDELINES.md' 2>/dev/null | sort
echo ""
echo "-- AI IDE configuration --"
for f in .cursor .cursor/rules .cursorrules .github/copilot-instructions.md \
.github/instructions .claude .claude/settings.json; do
[ -e "$f" ] && echo "./$f"
done
echo ""
echo "-- Agent skills --"
for d in .claude/skills .factory/skills; do
[ -d "$d" ] && echo "./$d/ ($(find "$d" -type f | wc -l | tr -d ' ') files)"
done
find . -maxdepth 3 -iname 'skill.md' 2>/dev/null | sort
echo ""
echo "-- Tool server configuration --"
find . -maxdepth 2 -name '.mcp.json' -o -name 'mcp.config.*' 2>/dev/null | sort
echo ""
echo "-- Agent prompt library --"
for d in .github/prompts prompts; do
[ -d "$d" ] && echo "./$d/ ($(find "$d" -type f | wc -l | tr -d ' ') files)"
done
echo ""
echo "-- README --"
[ -f README.md ] && echo "./README.md ($(wc -l < README.md) lines)" || echo "(not found)"
echo ""
echo "-- Contributing guide --"
find . -maxdepth 2 -iname 'CONTRIBUTING*' 2>/dev/null | sort
echo ""
echo "-- Architecture docs --"
find . -maxdepth 3 -iname 'ARCHITECTURE*' -o -iname 'DESIGN*' 2>/dev/null | sort
for d in doc/adr docs/adr decisions rfcs doc/design; do
[ -d "$d" ] && echo "./$d/ ($(find "$d" -type f | wc -l | tr -d ' ') files)"
done
echo ""
echo "-- API documentation --"
find . -maxdepth 3 -name 'openapi.yaml' -o -name 'openapi.json' -o -name 'swagger.yaml' \
-o -name 'swagger.json' 2>/dev/null | sort
find . -maxdepth 2 -name 'doc.go' 2>/dev/null | head -5
api_doc_count=$(find . -maxdepth 2 -name 'doc.go' 2>/dev/null | wc -l | tr -d ' ')
[ "$api_doc_count" -gt 5 ] && echo " ... and $((api_doc_count - 5)) more doc.go files"
echo ""
echo "-- Changelog --"
find . -maxdepth 1 -iname 'CHANGELOG*' -o -iname 'CHANGES*' -o -iname 'HISTORY*' 2>/dev/null | sort
echo ""
echo "-- Environment variable docs --"
find . -maxdepth 2 -name '.env.example' -o -name '.env.template' -o -name '.env.sample' 2>/dev/null | sort
echo ""
echo "-- Documentation site / directory --"
[ -d docs ] && echo "./docs/ ($(find docs -type f | wc -l | tr -d ' ') files)"
for f in docusaurus.config.* mkdocs.yml conf.py .vitepress/config.*; do
find . -maxdepth 2 -name "$(basename "$f")" 2>/dev/null
done
echo ""
echo "-- Examples directory --"
for d in examples _examples; do
[ -d "$d" ] && echo "./$d/ ($(find "$d" -type f | wc -l | tr -d ' ') files)"
done
echo ""
echo "-- Module-level READMEs --"
find . -mindepth 2 -maxdepth 3 -name 'README.md' 2>/dev/null | head -10
readme_count=$(find . -mindepth 2 -maxdepth 3 -name 'README.md' 2>/dev/null | wc -l | tr -d ' ')
[ "$readme_count" -gt 10 ] && echo " ... and $((readme_count - 10)) more"
echo " Total: $readme_count module READMEs"
#!/usr/bin/env bash
# Scan for Build & Dev Environment signals (Pillar 5)
# Helps the agent find relevant files — not a substitute for judgment.
REPO="${1:-.}"
cd "$REPO" 2>/dev/null || { echo "Cannot access $REPO"; exit 1; }
echo "=== Pillar 5: Build & Dev Environment ==="
echo ""
echo "-- Dependency lockfiles --"
for f in package-lock.json yarn.lock pnpm-lock.yaml bun.lockb \
Cargo.lock go.sum Gemfile.lock poetry.lock uv.lock \
Pipfile.lock composer.lock pubspec.lock; do
[ -f "$f" ] && echo "./$f"
done
echo ""
echo "-- Build commands --"
# Check for documented build commands in common files
for f in README.md AGENTS.md CONTRIBUTING.md Makefile Justfile; do
if [ -f "$f" ]; then
build_refs=$(grep -ci 'make build\|npm run build\|cargo build\|go build\|gradle build\|mvn.*package\|bundle exec' "$f" 2>/dev/null)
[ "$build_refs" -gt 0 ] && echo " $build_refs build command references in $f"
fi
done
echo ""
echo "-- Setup scripts --"
for f in bin/setup script/setup scripts/setup.sh scripts/bootstrap.sh \
script/bootstrap Makefile Justfile; do
[ -f "$f" ] && echo "./$f"
done
echo ""
echo "-- Dev container --"
if [ -d .devcontainer ]; then
echo ".devcontainer/:"
ls -1 .devcontainer/ 2>/dev/null | while read f; do echo " $f"; done
elif [ -f devcontainer.json ]; then
echo "./devcontainer.json"
else
echo " (not found)"
fi
echo ""
echo "-- Containerized services --"
find . -maxdepth 2 -name 'Dockerfile*' -o -name 'docker-compose*.yml' \
-o -name 'docker-compose*.yaml' -o -name 'compose.yml' -o -name 'compose.yaml' 2>/dev/null | sort
echo ""
echo "-- Reproducible environment --"
for f in flake.nix shell.nix default.nix devbox.json devbox.lock; do
[ -f "$f" ] && echo "./$f"
done
echo ""
echo "-- Tool version pinning --"
for f in .tool-versions mise.toml .mise.toml .node-version .nvmrc \
.python-version .ruby-version .go-version rust-toolchain.toml \
rust-toolchain .java-version .sdkmanrc; do
[ -f "$f" ] && echo "./$f"
done
echo ""
echo "-- Monorepo orchestration --"
# Check for workspace configs
if [ -f package.json ]; then
grep -q '"workspaces"' package.json 2>/dev/null && echo " workspaces in package.json"
fi
for f in pnpm-workspace.yaml lerna.json nx.json turbo.json rush.json; do
[ -f "$f" ] && echo "./$f"
done
if [ -f Cargo.toml ]; then
grep -q '\[workspace\]' Cargo.toml 2>/dev/null && echo " Cargo workspace in Cargo.toml"
fi
if [ -f go.work ]; then
echo "./go.work"
fi
echo ""
echo "-- Build caching --"
if [ -d .github/workflows ]; then
cache_count=$(grep -rl 'actions/cache\|buildx.*cache\|turbo.*cache\|ccache\|sccache' .github/workflows/ 2>/dev/null | wc -l | tr -d ' ')
echo " $cache_count workflows with cache configuration"
fi
[ -f turbo.json ] && grep -q 'cache' turbo.json 2>/dev/null && echo " Turborepo cache config"
echo ""
echo "-- Cross-platform support --"
if [ -d .github/workflows ]; then
for f in .github/workflows/*.yml .github/workflows/*.yaml; do
[ -f "$f" ] || continue
if grep -q 'matrix:' "$f" 2>/dev/null; then
os_line=$(grep -A10 'matrix:' "$f" | grep -i 'os:' | head -1 | tr -d ' ')
[ -n "$os_line" ] && echo " $(basename "$f"): $os_line"
fi
done
fi
echo ""
echo "-- Cloud dev environment --"
[ -f .gitpod.yml ] && echo "./.gitpod.yml"
if [ -d .devcontainer ]; then
grep -q 'codespaces\|ghcr.io' .devcontainer/devcontainer.json 2>/dev/null \
&& echo " Codespaces support in devcontainer.json"
fi
echo ""
echo "-- Package manager configuration --"
for f in .npmrc .yarnrc .yarnrc.yml .pnpmrc pip.conf .cargo/config.toml \
.cargo/config gradle.properties; do
[ -f "$f" ] && echo "./$f"
done
#!/usr/bin/env bash
# Scan for Feedback Loops signals (Pillar 2)
# Helps the agent find relevant files — not a substitute for judgment.
REPO="${1:-.}"
cd "$REPO" 2>/dev/null || { echo "Cannot access $REPO"; exit 1; }
echo "=== Pillar 2: Feedback Loops ==="
echo ""
echo "-- Linter configuration --"
find . -maxdepth 2 \( \
-name '.eslintrc*' -o -name 'eslint.config.*' \
-o -name 'ruff.toml' -o -name '.golangci.yml' -o -name '.golangci.yaml' \
-o -name 'clippy.toml' -o -name '.clippy.toml' \
-o -name '.pylintrc' -o -name 'pylintrc' \
-o -name 'biome.json' -o -name 'biome.jsonc' \
-o -name '.swiftlint.yml' -o -name '.ktlint*' \
\) 2>/dev/null | sort
# Check pyproject.toml for ruff/pylint
if [ -f pyproject.toml ]; then
grep -l -i '\[tool\.ruff\]\|\[tool\.pylint\]\|\[tool\.flake8\]' pyproject.toml 2>/dev/null \
&& echo " (also: linter config in pyproject.toml)"
fi
echo ""
echo "-- Formatter configuration --"
find . -maxdepth 2 \( \
-name '.prettierrc*' -o -name 'prettier.config.*' \
-o -name 'rustfmt.toml' -o -name '.rustfmt.toml' \
-o -name '.clang-format' \
-o -name '.editorconfig' \
\) 2>/dev/null | sort
if [ -f pyproject.toml ]; then
grep -l -i '\[tool\.black\]\|\[tool\.ruff\.format\]\|\[tool\.isort\]' pyproject.toml 2>/dev/null \
&& echo " (also: formatter config in pyproject.toml)"
fi
echo ""
echo "-- Type checking --"
find . -maxdepth 2 -name 'tsconfig.json' -o -name 'tsconfig.*.json' 2>/dev/null | sort
if [ -f tsconfig.json ]; then
grep -q '"strict"' tsconfig.json 2>/dev/null && echo " (strict mode in tsconfig.json)"
fi
find . -maxdepth 2 -name 'mypy.ini' -o -name '.mypy.ini' 2>/dev/null | sort
if [ -f pyproject.toml ]; then
grep -q '\[tool\.mypy\]\|\[tool\.pyright\]' pyproject.toml 2>/dev/null \
&& echo " (type checker config in pyproject.toml)"
fi
find . -maxdepth 1 -name 'py.typed' 2>/dev/null
echo ""
echo "-- Pre-commit hooks --"
for f in .pre-commit-config.yaml .husky lefthook.yml .lefthook.yml; do
[ -e "$f" ] && echo "./$f"
done
if [ -f package.json ]; then
grep -q 'lint-staged' package.json 2>/dev/null && echo " (lint-staged in package.json)"
fi
echo ""
echo "-- Test directories --"
for d in test tests __tests__ spec test/unit test/integration tests/unit tests/integration \
test/e2e tests/e2e e2e cypress playwright; do
[ -d "$d" ] && echo "./$d/ ($(find "$d" -maxdepth 1 -type f | wc -l | tr -d ' ') top-level files)"
done
echo ""
echo "-- Test file count --"
test_files=$(find . -maxdepth 5 \( \
-name '*_test.go' -o -name '*_test.py' -o -name 'test_*.py' \
-o -name '*.spec.ts' -o -name '*.test.ts' -o -name '*.spec.js' -o -name '*.test.js' \
-o -name '*_test.rb' -o -name '*_spec.rb' \
-o -name '*_test.rs' \
\) 2>/dev/null | wc -l | tr -d ' ')
echo " $test_files test files found"
echo ""
echo "-- Test coverage --"
find . -maxdepth 2 \( \
-name '.codecov.yml' -o -name 'codecov.yml' \
-o -name '.coveragerc' -o -name 'coverage.config.*' \
-o -name 'jest.config.*' \
\) 2>/dev/null | sort
if [ -f pyproject.toml ]; then
grep -q '\[tool\.coverage\]\|\[tool\.pytest\.ini_options\]' pyproject.toml 2>/dev/null \
&& echo " (coverage/pytest config in pyproject.toml)"
fi
if [ -f jest.config.js ] || [ -f jest.config.ts ]; then
grep -l 'coverageThreshold' jest.config.* 2>/dev/null
fi
echo ""
echo "-- CI pipelines --"
if [ -d .github/workflows ]; then
echo ".github/workflows/:"
ls -1 .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null | while read f; do
echo " $(basename "$f")"
done
fi
for f in .circleci/config.yml .gitlab-ci.yml Jenkinsfile .travis.yml; do
[ -f "$f" ] && echo "./$f"
done
echo ""
echo "-- Config/schema validation --"
find . -maxdepth 2 -name '.yamllint*' -o -name 'taplo.toml' 2>/dev/null | sort
if [ -d .github/workflows ]; then
grep -rl 'actionlint\|yamllint\|schema.*validate' .github/workflows/ 2>/dev/null | head -3
fi
echo ""
echo "-- Snapshot tests --"
snap_count=$(find . -maxdepth 5 -name '__snapshots__' -o -name '*.snap' 2>/dev/null | wc -l | tr -d ' ')
golden_count=$(find . -maxdepth 4 -name 'testdata' -type d 2>/dev/null | wc -l | tr -d ' ')
echo " $snap_count snapshot dirs/files, $golden_count testdata dirs"
echo ""
echo "-- Benchmark suite --"
for d in bench benchmarks benchmark; do
[ -d "$d" ] && echo "./$d/ ($(find "$d" -type f | wc -l | tr -d ' ') files)"
done
bench_files=$(find . -maxdepth 4 -name '*_bench_test.go' -o -name '*benchmark*' -type f 2>/dev/null | wc -l | tr -d ' ')
echo " $bench_files benchmark files found"
echo ""
echo "-- Spell checking --"
find . -maxdepth 2 -name '.cspell.json' -o -name 'cspell.json' -o -name 'typos.toml' \
-o -name '.typos.toml' 2>/dev/null | sort
if [ -f .pre-commit-config.yaml ]; then
grep -q 'codespell\|cspell\|typos' .pre-commit-config.yaml 2>/dev/null \
&& echo " (spell checker in pre-commit config)"
fi
#!/usr/bin/env bash
# Scan for Policy & Governance signals (Pillar 4)
# Helps the agent find relevant files — not a substitute for judgment.
REPO="${1:-.}"
cd "$REPO" 2>/dev/null || { echo "Cannot access $REPO"; exit 1; }
echo "=== Pillar 4: Policy & Governance ==="
echo ""
echo "-- .gitignore --"
if [ -f .gitignore ]; then
lines=$(wc -l < .gitignore | tr -d ' ')
echo "./.gitignore ($lines lines)"
# Check for agent-aware entries
agent_entries=$(grep -ci 'cursor\|claude\|copilot\|\.agent\|\.mcp' .gitignore 2>/dev/null)
[ "$agent_entries" -gt 0 ] && echo " ($agent_entries agent-related ignore entries)"
else
echo " (not found)"
fi
echo ""
echo "-- License --"
find . -maxdepth 1 -iname 'LICENSE*' -o -iname 'COPYING*' -o -iname 'MIT-LICENSE' 2>/dev/null | sort
echo ""
echo "-- Code ownership --"
find . -maxdepth 3 -name 'CODEOWNERS' 2>/dev/null | sort
if [ -f CODEOWNERS ] || [ -f .github/CODEOWNERS ] || [ -f docs/CODEOWNERS ]; then
f=$(find . -maxdepth 3 -name 'CODEOWNERS' 2>/dev/null | head -1)
rules=$(grep -c '^[^#]' "$f" 2>/dev/null | tr -d ' ')
echo " ($rules ownership rules)"
fi
echo ""
echo "-- Security policy --"
find . -maxdepth 3 -iname 'SECURITY*' 2>/dev/null | sort
echo ""
echo "-- Code of conduct --"
find . -maxdepth 2 -iname 'CODE_OF_CONDUCT*' -o -iname 'CONDUCT*' 2>/dev/null | sort
echo ""
echo "-- AI usage policy --"
# Check common locations for AI policy mentions
for f in AGENTS.md CLAUDE.md CONTRIBUTING.md; do
if [ -f "$f" ]; then
ai_mentions=$(grep -ci 'ai policy\|ai usage\|agent boundar\|ai contribut\|llm\|copilot' "$f" 2>/dev/null)
[ "$ai_mentions" -gt 0 ] && echo " $ai_mentions AI policy references in $f"
fi
done
echo ""
echo "-- Secrets management --"
if [ -d .github/workflows ]; then
secrets_refs=$(grep -roh '\${{ secrets\.[A-Z_]*' .github/workflows/ 2>/dev/null | sort -u | wc -l | tr -d ' ')
echo " $secrets_refs distinct secrets referenced in CI"
fi
find . -maxdepth 2 -name '.env.example' -o -name '.env.template' 2>/dev/null | sort
find . -maxdepth 2 -name 'vault.hcl' -o -name '.vault-token' 2>/dev/null | sort
echo ""
echo "-- Security scanning --"
if [ -d .github/workflows ]; then
for scanner in codeql snyk trivy gosec semgrep; do
grep -ril "$scanner" .github/workflows/ 2>/dev/null | while read f; do
echo " $scanner in $(basename "$f")"
done
done
fi
find . -maxdepth 2 -name '.snyk' -o -name '.trivyignore' 2>/dev/null | sort
echo ""
echo "-- Git attributes --"
if [ -f .gitattributes ]; then
lines=$(wc -l < .gitattributes | tr -d ' ')
echo "./.gitattributes ($lines lines)"
linguist=$(grep -c 'linguist' .gitattributes 2>/dev/null)
[ "$linguist" -gt 0 ] && echo " ($linguist linguist overrides)"
lfs=$(grep -c 'filter=lfs' .gitattributes 2>/dev/null)
[ "$lfs" -gt 0 ] && echo " ($lfs LFS-tracked patterns)"
else
echo " (not found)"
fi
echo ""
echo "-- Contributor agreement --"
find . -maxdepth 2 -iname 'DCO*' -o -iname 'CLA*' 2>/dev/null | sort
for f in CONTRIBUTING.md .github/workflows/*.yml; do
[ -f "$f" ] && grep -qi 'signed-off-by\|DCO\|CLA\|contributor license' "$f" 2>/dev/null \
&& echo " DCO/CLA reference in $(basename "$f")"
done
echo ""
echo "-- Governance model --"
find . -maxdepth 2 -iname 'GOVERNANCE*' -o -iname 'MAINTAINERS*' -o -iname 'OWNERS*' 2>/dev/null | sort
echo ""
echo "-- CI workflow validation --"
if [ -d .github/workflows ]; then
grep -rl 'actionlint' .github/workflows/ 2>/dev/null | head -3
fi
if [ -f .pre-commit-config.yaml ]; then
grep -q 'actionlint' .pre-commit-config.yaml 2>/dev/null && echo " actionlint in pre-commit"
fi
echo ""
echo "-- Environment separation --"
find . -maxdepth 2 -name '.env.test' -o -name '.env.production' -o -name '.env.staging' \
-o -name '.env.development' 2>/dev/null | sort
for d in config/environments environments; do
[ -d "$d" ] && echo "./$d/ ($(ls "$d" | wc -l | tr -d ' ') environments)"
done
#!/usr/bin/env bash
# Scan for Workflows & Automation signals (Pillar 3)
# Helps the agent find relevant files — not a substitute for judgment.
REPO="${1:-.}"
cd "$REPO" 2>/dev/null || { echo "Cannot access $REPO"; exit 1; }
echo "=== Pillar 3: Workflows & Automation ==="
echo ""
echo "-- Issue templates --"
if [ -d .github/ISSUE_TEMPLATE ]; then
echo ".github/ISSUE_TEMPLATE/:"
ls -1 .github/ISSUE_TEMPLATE/ 2>/dev/null | while read f; do echo " $f"; done
else
echo " (not found)"
fi
echo ""
echo "-- PR template --"
find . -maxdepth 3 -iname 'pull_request_template*' 2>/dev/null | sort
[ -f .github/pull_request_template.md ] || echo " (not found)"
echo ""
echo "-- Dependency update automation --"
for f in .github/dependabot.yml .github/dependabot.yaml renovate.json .renovaterc \
.renovaterc.json renovate.json5; do
[ -f "$f" ] && echo "./$f"
done
echo ""
echo "-- Release automation --"
if [ -d .github/workflows ]; then
grep -ril 'release\|publish\|deploy' .github/workflows/ 2>/dev/null | while read f; do
echo " $(basename "$f")"
done
fi
for f in .releaserc .releaserc.json .releaserc.yml release-please-config.json \
.goreleaser.yml .goreleaser.yaml; do
[ -f "$f" ] && echo "./$f"
done
echo ""
echo "-- Branch protection signals --"
# Can't check GitHub settings from filesystem, but look for merge queue triggers
if [ -d .github/workflows ]; then
grep -rl 'merge_group' .github/workflows/ 2>/dev/null | while read f; do
echo " merge_group trigger in $(basename "$f")"
done
fi
echo ""
echo "-- Merge automation --"
find . -maxdepth 2 -name '.mergify.yml' -o -name 'mergify.yml' 2>/dev/null | sort
if [ -d .github/workflows ]; then
grep -rl 'auto-merge\|automerge\|gh pr merge' .github/workflows/ 2>/dev/null | head -3
fi
echo ""
echo "-- Task runner --"
for f in Makefile GNUmakefile makefile Justfile justfile Taskfile.yml taskfile.yml \
Rakefile Earthfile; do
[ -f "$f" ] && echo "./$f"
done
if [ -f package.json ]; then
script_count=$(python3 -c "import json; d=json.load(open('package.json')); print(len(d.get('scripts',{})))" 2>/dev/null)
[ -n "$script_count" ] && echo " package.json: $script_count scripts"
fi
echo ""
echo "-- Structured change tracking --"
[ -d .changeset ] && echo ".changeset/ ($(ls .changeset/*.md 2>/dev/null | wc -l | tr -d ' ') pending changesets)"
find . -maxdepth 2 -name 'commitlint.config.*' -o -name '.commitlintrc*' 2>/dev/null | sort
if [ -d .github/workflows ]; then
grep -rl 'conventional-commits\|commitlint\|semantic-pull-request' .github/workflows/ 2>/dev/null | head -3
fi
echo ""
echo "-- CI concurrency control --"
if [ -d .github/workflows ]; then
concurrency_count=$(grep -rl 'concurrency:' .github/workflows/ 2>/dev/null | wc -l | tr -d ' ')
cancel_count=$(grep -rl 'cancel-in-progress' .github/workflows/ 2>/dev/null | wc -l | tr -d ' ')
echo " $concurrency_count workflows with concurrency groups, $cancel_count with cancel-in-progress"
fi
echo ""
echo "-- Automated release notes --"
for f in release-please-config.json .github/release.yml cliff.toml .cliff.toml; do
[ -f "$f" ] && echo "./$f"
done
if [ -d .github/workflows ]; then
grep -rl 'auto-changelog\|conventional-changelog\|git-cliff\|release-please' .github/workflows/ 2>/dev/null | head -3
fi
echo ""
echo "-- Stale issue management --"
if [ -d .github/workflows ]; then
grep -rl 'stale' .github/workflows/ 2>/dev/null | while read f; do
echo " $(basename "$f")"
done
fi
[ -f .github/stale.yml ] && echo ".github/stale.yml"
echo ""
echo "-- Label automation --"
find . -maxdepth 3 -name 'labeler.yml' -o -name '.github/labeler.yml' -o -name 'label-sync*' 2>/dev/null | sort
echo ""
echo "-- Multi-platform CI --"
if [ -d .github/workflows ]; then
grep -rl 'matrix:' .github/workflows/ 2>/dev/null | while read f; do
os_line=$(grep -A5 'matrix:' "$f" | grep -i 'os:' | head -1)
[ -n "$os_line" ] && echo " $(basename "$f"): $os_line"
done
fi
echo ""
echo "-- Deployment automation --"
if [ -d .github/workflows ]; then
grep -ril 'deploy' .github/workflows/ 2>/dev/null | while read f; do
echo " $(basename "$f")"
done
fi
[ -f vercel.json ] && echo "./vercel.json"
[ -f netlify.toml ] && echo "./netlify.toml"
[ -f fly.toml ] && echo "./fly.toml"
[ -f render.yaml ] && echo "./render.yaml"