Build an inventory of what's in the repo so other skills don't have to re-discover it. The output is a structured summary, not a written file — the orchestrator passes it as context to the next sub-skill.
What to scan, in order
Stop at the first finding for each section unless the section says otherwise. Don't recurse into node_modules/, .git/, dist/, build/, .turbo/, .next/, __pycache__/, .venv/, target/.
1. Top-level fingerprint
ls -la at repo root + git log --oneline -10. Capture:
- Repo name (from
package.json:name,pyproject.toml:[project].name,Cargo.toml:[package].name, or git remote). - Default branch (
git symbolic-ref refs/remotes/origin/HEADor fall back tomain/master). - Code host (parse
git remote get-url origin— github.com / gitlab / bitbucket / self-hosted). - Existing
AGENTS.md/CLAUDE.md/.cursorrules/.github/copilot-instructions.md/CONTRIBUTING.md— read these in full. Existing conventions are gospel.
2. Languages + package managers
| Signal file | Language / package manager |
|---|---|
package.json |
JavaScript / TypeScript |
pnpm-lock.yaml, pnpm-workspace.yaml |
pnpm + (likely) workspaces |
yarn.lock |
yarn |
package-lock.json |
npm |
tsconfig.json (one or many) |
TypeScript |
pyproject.toml |
Python (modern) |
requirements*.txt, setup.py, setup.cfg |
Python (legacy) |
Cargo.toml |
Rust |
go.mod |
Go |
Gemfile |
Ruby |
pom.xml, build.gradle* |
Java / Kotlin |
composer.json |
PHP |
Capture every match — many repos are polyglot. Read each lockfile / package.json / pyproject.toml to extract direct dependencies (skip transitive).
3. Frameworks (from dependencies)
Match top-level deps against this table:
| Dep / signal | Framework |
|---|---|
react, react-dom |
React |
next |
Next.js (check next.config.* for App Router signals: app/ directory) |
vite, @vitejs/* |
Vite |
@medplum/core, @medplum/fhirtypes, @medplum/react |
Medplum (FHIR backend) |
mantine, @mantine/* |
Mantine UI |
tailwindcss |
Tailwind |
@vercel/* |
Vercel platform / SDKs |
playwright, @playwright/test |
Playwright e2e |
vitest, jest |
Vitest / Jest |
biome, @biomejs/biome |
Biome lint+format |
eslint, prettier |
ESLint / Prettier |
Django (in pyproject / requirements) |
Django |
psqlextra, django-postgres-extra |
Django + PG partitioning |
strawberry-graphql |
Strawberry GraphQL |
fastapi |
FastAPI |
flask |
Flask |
pytest |
pytest |
mypy, ruff, black |
Python lint/type tools |
@tanstack/react-start, @tanstack/start |
TanStack Start (check @tanstack/react-router) |
react-router, react-router-dom, @react-router/* |
React Router |
tRPC, @trpc/* |
tRPC |
prisma, @prisma/client |
Prisma |
drizzle-orm |
Drizzle |
mongoose |
Mongoose / MongoDB |
Record stack matches — these drive which template directories vinta-bootstrap-ai-tools copies from.
4. Build / dev / lint / test commands
For Node/TS: read package.json:scripts. Capture: dev, build, test, test:*, lint, lint:fix, format, typecheck. Also: workspace tasks (turbo run …, pnpm --filter …).
For Python: read pyproject.toml:[tool.poetry.scripts] / [project.scripts] + Makefile + tox.ini + noxfile.py. Capture: test runner command, lint command, type-check command, dev server command.
For other languages: read Makefile + justfile + language-specific files (Cargo.toml:[bin], etc).
Note: many repos have the test command in CI config but not surfaced as a top-level script. Read .github/workflows/*.yml / .gitlab-ci.yml / .circleci/config.yml / Jenkinsfile to confirm.
5. Monorepo shape
pnpm-workspace.yaml→ list workspaces.turbo.json→ tasks + pipeline graph.nx.json/lerna.json→ Nx / Lerna.apps/+lib/(orapps/+packages/) directory pattern → conventional monorepo layout.- Single-package repos: report as such; downstream skills need to know.
For each app/package: name + path + framework (cross-ref the Frameworks (from dependencies) scan above) + entry point.
6. Tests
- Unit / integration: where are they?
apps/*/src/**/*.test.ts,tests/,__tests__/,<pkg>/tests/unit,<pkg>/tests/integration. Glob. - E2E:
e2e/,playwright/,cypress/. Read fixtures + setup files for: auth strategy, seed helpers, tenant scoping in seeds. - Test data: factories, fixtures, mocks. Note conventions (
@medplum/mock,factory_boy, MSW, etc). - Unit-test conventions (feeds
write-unit-test). Read a representative sample of existing unit tests (not e2e) and infer the dominant pattern for each axis below. These pre-fillskills.write-unit-test.*in the bootstrap interview (group C.9), so the shipped skill matches the suite instead of imposing a house style. Reportframework-defaultfor any axis where the suite is mixed or there's no signal (greenfield):- test_style —
functions(standalonedef test_x/ bareit(...)) vsclasses(TestCasesubclasses,describegrouping). Which dominates? - data_setup —
factories(factory_boy / FactoryBot / builder helpers — cross-reftest_data_helpers),fixtures(pytest fixtures / fixture files /setUpTestData), orinline(objects built in the test body). - assertion_style —
plain-assert(Pythonassert/ JSexpect) vsframework-methods(self.assertEqual-family). - db_isolation —
transaction-rollback(DjangoTestCase, pytest-djangodb, SQLAlchemy savepoint fixtures),truncate(TransactionTestCase), orrecreate. Read the test base classes / DB fixtures to tell. - extras — any other recurring convention worth carrying (test file co-location + naming pattern, one-assertion-per-test, a house HTTP-mock helper / recorded-cassette pattern, custom assertion helpers). List them; they seed
additional_conventions.
- test_style —
7. Deploy / release model
.github/workflows/deploy*.yml/.gitlab-ci.ymldeploy stages — capture target (Vercel, AWS, Heroku, K8s, custom), trigger (push to main vs release tag vs manual), environments named (staging,production,preview).vercel.json/vercel.ts→ Vercel project config.Dockerfile+docker-compose*.yml→ containerized.helm/,k8s/,kustomize/→ Kubernetes.scripts/deploy*/scripts/release*→ manual deploy paths.- For Medplum repos: look for
pnpm bots:deploy,deploy-bots.ts, AccessPolicy seed scripts.
8. Environments + multi-tenancy
.env.examplefiles at root + per-app — list var names (not values), note prefix patterns (VITE_,NEXT_PUBLIC_,REACT_APP_).- Vite
envPrefixallowlist (vite.config.ts). - Turbo
tasks.<name>.envarrays (cache hash inputs). - Multi-tenancy signals:
tenant_idcolumns in models / SQL schemas → row-level multi-tenancy.meta.accountreferences in FHIR resource creation → Medplum tenant compartmenting.Organizationresource +_compartment=Organization/<id>queries → Medplum org-scoped.<env>__<name>prefix patterns in deploy scripts → per-env isolation in shared backend.psqlextrapartitioning by tenant key → partition-based isolation.- Single-tenant: explicitly note absence of these signals.
9. CI / CD
- CI provider: GitHub Actions, GitLab CI, CircleCI, Jenkins, Buildkite, custom.
- Workflow files, named jobs, on-which-events (push, pull_request, schedule, release).
- Required checks (branch protection if visible via
.github/branch-protection.ymlor surfaced in CONTRIBUTING). - Pre-commit hooks:
.pre-commit-config.yaml,.husky/,lefthook.yml.
10. Documentation already present
README.mdat root + per-app.docs/directory.- Architecture decision records (
docs/adr/,docs/architecture/).
11. Existing AI-tooling artifacts
This is a load-bearing input for the rest of the bootstrap flow — surface every artifact found, even partial/legacy ones. Read each in full; they tell you what conventions already exist so the downstream vinta-write-agents-md / vinta-derive-subagents / vinta-derive-skills steps can preserve, merge, or migrate rather than overwrite.
Instruction documents — search for any of these and capture their content:
AGENTS.md(root + per-app in monorepos; also the legacyai-tools/AGENTS.mdpath).CLAUDE.md,.cursorrules,.cursor/rules/*.mdc,.github/copilot-instructions.md.- Codex / Cursor / Copilot instructions inside vendor dirs (
.codex/AGENTS.md, etc.). - Anything tagged "AI conventions" / "Coding agent guide" / "LLM rules" in CONTRIBUTING / docs.
Skills — for each vendor path, list every skill found with its name + description (from frontmatter):
| Path | What lives there |
|---|---|
.claude/skills/<name>/SKILL.md |
Claude Code project skills |
.cursor/skills/<name>/SKILL.md |
Cursor project skills |
.codex/skills/<name>/SKILL.md |
Codex project skills (legacy path) |
.github/skills/<name>/SKILL.md |
Copilot project skills |
.agents/skills/<name>/SKILL.md |
Universal skills (Codex/Cursor/Copilot) |
ai-tools/skills/<name>/SKILL.md |
Vinta canonical layout (already-bootstrapped) |
For each skill, also classify:
vinta-managed— directory name starts withvinta-(installed byvinta-ai-workflows; can be left alone or refreshed via that CLI).foundation-shape— name matches the Vinta foundation set (plan-feature,create-spec,create-qa-use-cases,implement-plan,implement-phase,review-phase,integrate-phase,amend-plan,add-e2e-test,add-env-var,write-unit-test).implement-phase/review-phase/integrate-phaseare the plan-execution sub-skills co-shipped withimplement-plan.project-custom— anything else; written by the team.
Sub-agents — list every agent file with its name + description:
| Path | Format | Purpose |
|---|---|---|
.claude/agents/<name>.md |
markdown + frontmatter | Claude Code |
.cursor/agents/<name>.md |
markdown + frontmatter | Cursor |
.codex/agents/<name>.toml |
TOML | Codex |
.github/agents/<name>.agent.md |
markdown + frontmatter | Copilot |
ai-tools/agents/<name>.yaml |
YAML | Vinta canonical |
For each agent, also classify:
foundation-shape— name matchesimplementer/reviewer/fixer.stack-specialist— recognizable stack agent (e.g.migration-author,deploy-author).project-custom— anything else.
Setup wiring — note presence of:
ai-tools/scripts/setup-ai-tools.mjs(Vinta canonical multi-vendor setup).package.json#scripts.setup:ai-toolsor similar alias.- Symlinks:
CLAUDE.md → AGENTS.md,.github/copilot-instructions.md → ../AGENTS.md,.claude/skills → ../ai-tools/skills, etc. - Legacy layout: a root
AGENTS.mdthat is a symlink intoai-tools/AGENTS.mdpredates the move of the doc to the repo root. Record it — vinta-sync-ai-tools migrates it.
Plan/spec docs — flag presence (full inventory comes later from vinta-migrate-plans-specs):
ai-plans/directory contents.- Loose
IMPLEMENTATION_PLAN.md,SPEC.md,RFC.mdat root or underdocs/.
PR / MR templates — list every existing template file (case-insensitive). Used by implement-plan / amend-plan to scaffold the prs-context # Description so generated PRs match the project's existing convention. Search:
- GitHub:
.github/pull_request_template.md(andPULL_REQUEST_TEMPLATE.mdcasing)..github/PULL_REQUEST_TEMPLATE/*.md(multi-template directory).pull_request_template.mdandPULL_REQUEST_TEMPLATE.mdat repo root.docs/pull_request_template.mdanddocs/PULL_REQUEST_TEMPLATE.md.
- GitLab:
.gitlab/merge_request_templates/*.md.
- Bitbucket / others: typically configured server-side, no file convention. Note in inventory if user-supplied.
For each template found, capture:
- Path (relative to repo root).
- A one-line summary of the section structure (
## Summary,## Test plan,## Screenshots,<!-- comments -->, etc.) so downstream skills know how to fill it.
Output goes into existing_ai_artifacts.pr_templates (see schema below). The full content is read on demand by implement-plan / amend-plan when drafting prs-context files; analyze-codebase only enumerates.
If anything is found, do NOT overwrite — the downstream skills will read this section and decide preserve / merge / migrate per artifact, gated on user confirmation in vinta-bootstrap-ai-tools's Existing AI artifacts (per-artifact disposition) interview group.
Output: structured inventory
Return a single structured object (in conversation, as a tool result, or just printed for the user / orchestrator to read). Shape:
repo:
name: <string>
default_branch: <string>
code_host: github | gitlab | bitbucket | self-hosted | unknown
existing_ai_artifacts:
instructions:
- { path: AGENTS.md, content: <full text> }
- { path: .github/copilot-instructions.md, content: <full text> }
- ...
skills:
- { path: .claude/skills/checkout-flow/SKILL.md, name: checkout-flow,
description: <from frontmatter>, classification: project-custom }
- { path: ai-tools/skills/plan-feature/SKILL.md, name: plan-feature,
description: <...>, classification: foundation-shape }
- ...
agents:
- { path: .claude/agents/migration-author.md, name: migration-author,
description: <...>, classification: stack-specialist }
- ...
setup:
- ai-tools/scripts/setup-ai-tools.mjs
- package.json#scripts.setup:ai-tools
pr_templates:
- { path: .github/pull_request_template.md, sections: [Summary, Test plan, Screenshots] }
- { path: .github/PULL_REQUEST_TEMPLATE/feature.md, sections: [...] }
plans_dir_present: true | false # full migration list comes from vinta-migrate-plans-specs
# downstream skills MUST read existing_ai_artifacts before drafting anything new.
languages:
- typescript | python | rust | go | ...
package_managers:
- pnpm | npm | yarn | poetry | pip | cargo | ...
frameworks:
# each with version range + path of signal file
- { name: react, version: "^19", signal: package.json }
- { name: medplum, version: "^5", signal: package.json }
- { name: django, version: "^5.1", signal: pyproject.toml }
- ...
monorepo:
type: turbo | pnpm-workspaces | nx | lerna | none
apps:
- { name: <string>, path: <string>, framework: <string>, port: <int|null> }
packages:
- { name: <string>, path: <string>, role: shared-lib | sdk | ... }
commands:
install: <e.g. pnpm install>
dev: <e.g. pnpm dev>
build: <e.g. pnpm build>
test_unit: <e.g. pnpm test>
test_e2e: <e.g. pnpm test:e2e>
lint: <e.g. pnpm lint>
format: <e.g. pnpm format>
typecheck: <e.g. pnpm build (tsc) — or null if no separate command>
tests:
unit_framework: vitest | jest | pytest | ...
unit_paths: [<glob>]
e2e_framework: playwright | cypress | none
e2e_paths: [<path>]
test_data_helpers: [<file>] # factories, mock clients, seed scripts
conventions: # inferred dominant patterns → skills.write-unit-test.* (framework-default when mixed / no signal)
test_style: functions | classes | framework-default
data_setup: factories | fixtures | inline | framework-default
assertion_style: plain-assert | framework-methods | framework-default
db_isolation: transaction-rollback | truncate | recreate | framework-default
extras: [<free-form recurring convention>] # seeds additional_conventions; [] when none
deploy:
targets: [vercel, aws-ecs, heroku, k8s, medplum-bots, npm-publish, ...]
envs: [staging, production, preview, dev-<handle>, ...]
ci_provider: github-actions | gitlab-ci | circleci | jenkins | none
workflow_files: [<path>]
triggers: [push:main, release, manual, ...]
manual_deploy_paths: [<script paths that humans run by hand, e.g. npx medplum post Bundle ...>]
env_model:
example_files: [<.env.example paths>]
vars_count: <int>
vite_envprefix: [<list>] | null
turbo_env_lists: { <task>: [<vars>] } | null
multi_tenancy:
pattern: row-level | medplum-compartment | partitioned | per-env-prefix | none
evidence: [<file:line refs>]
ci:
provider: github-actions | gitlab-ci | ...
jobs: [<name>]
pre_commit: husky | pre-commit | lefthook | none
docs:
readme: present | absent
docs_dir: <path or null>
adrs: <path or null>
stacks_matched:
# cross-ref to bootstrap-ai-tools/resources/stacks/<name>
- medplum
- typescript-monorepo
- django
- ...
Rules
- Read, don't guess. Every claim in the inventory cites a file. If you can't find the signal, the field is
nullorunknown, not a guess. - Don't run code. No
pnpm install, nopytest, no shell commands beyondls,cat,grep,git log. Pure read. - Stop at the first match per section unless the section says otherwise. A repo is a TypeScript repo if
package.json+tsconfig.jsonexist; you don't need to grep every.tsfile to confirm. - Existing AI artifacts override stack defaults. If
AGENTS.mdexists, its content beats your detection. Surface conflicts (e.g. AGENTS.md says "use yarn" but lockfile ispnpm-lock.yaml) as findings, don't silently pick one. - Never use
§Nshorthand in any inventory output, summary, or downstream prompt. Reference sections by their full heading name.§Nreferences break when the source's section numbering changes.
Pitfalls
- Treating dev-deps as framework signals. A repo with
playwrightindevDependenciesdoesn't necessarily have e2e tests — confirm by checking forplaywright.config.*+e2e/or equivalent. - Inferring multi-tenancy from a
tenant_idcolumn on one model. Check that the column is on the hot tables and that queries actually filter by it. A vestigial column is not a tenancy pattern. - Reporting
medplum-botsas a deploy target without verifying.@medplum/corein deps → SDK usage. Abots/directory +deploy-bots.tsscript → actual bot deploy path. Different things. - Polyglot repos with mismatched conventions per language. Report each language's conventions separately if they diverge (e.g. JS uses Biome, Python uses ruff). Don't average.