{"kind":"Skill","metadata":{"namespace":"community","name":"acquire-codebase-knowledge","version":"0.1.0"},"spec":{"description":"Use this skill when the user explicitly asks to map, document, or onboard into an existing codebase. Trigger for prompts like \"map this codebase\", \"document this architecture\", \"onboard me to this repo\", or \"create codebase docs\". Do not trigger for routine feature implementation, bug fixes, or narrow code edits unless the user asks for repository-level discovery.","files":{"SKILL.md":"---\nname: acquire-codebase-knowledge\ndescription: 'Use this skill when the user explicitly asks to map, document, or onboard into an existing codebase. Trigger for prompts like \"map this codebase\", \"document this architecture\", \"onboard me to this repo\", or \"create codebase docs\". Do not trigger for routine feature implementation, bug fixes, or narrow code edits unless the user asks for repository-level discovery.'\nlicense: MIT\ncompatibility: 'Cross-platform. Requires Python 3.8+ and git. Run scripts/scan.py from the target project root.'\nmetadata:\n  version: \"1.3\"\n  enhancements:\n    - Multi-language manifest detection (25+ languages supported)\n    - CI/CD pipeline detection (10+ platforms)\n    - Container \u0026 orchestration detection\n    - Code metrics by language\n    - Security \u0026 compliance config detection\n    - Performance testing markers\nargument-hint: 'Optional: specific area to focus on, e.g. \"architecture only\", \"testing and concerns\"'\n---\n\n# Acquire Codebase Knowledge\n\nProduces seven populated documents in `docs/codebase/` covering everything needed to work effectively on the project. Only document what is verifiable from files or terminal output — never infer or assume.\n\n## Output Contract (Required)\n\nBefore finishing, all of the following must be true:\n\n1. Exactly these files exist in `docs/codebase/`: `STACK.md`, `STRUCTURE.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `INTEGRATIONS.md`, `TESTING.md`, `CONCERNS.md`.\n2. Every claim is traceable to source files, config, or terminal output.\n3. Unknowns are marked as `[TODO]`; intent-dependent decisions are marked `[ASK USER]`.\n4. Every document includes a short \"evidence\" list with concrete file paths.\n5. Final response includes numbered `[ASK USER]` questions and intent-vs-reality divergences.\n\n## Workflow\n\nCopy and track this checklist:\n\n```\n- [ ] Phase 1: Run scan, read intent documents\n- [ ] Phase 2: Investigate each documentation area\n- [ ] Phase 3: Populate all seven docs in docs/codebase/\n- [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] items\n```\n\n## Focus Area Mode\n\nIf the user supplies a focus area (for example: \"architecture only\" or \"testing and concerns\"):\n\n1. Always run Phase 1 in full.\n2. Fully complete focus-area documents first.\n3. For non-focus documents not yet analyzed, keep required sections present and mark unknowns as `[TODO]`.\n4. Still run the Phase 4 validation loop on all seven documents before final output.\n\n### Phase 1: Scan and Read Intent\n\n1. Run the scan script from the target project root:\n   ```bash\n   python3 \"$SKILL_ROOT/scripts/scan.py\" --output docs/codebase/.codebase-scan.txt\n   ```\n   Where `$SKILL_ROOT` is the absolute path to the skill folder. Works on Windows, macOS, and Linux.\n\n   **Quick start:** If you have the path inline:\n   ```bash\n   python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt\n   ```\n\n2. Search for `PRD`, `TRD`, `README`, `ROADMAP`, `SPEC`, `DESIGN` files and read them.\n3. Summarise the stated project intent before reading any source code.\n\n### Phase 2: Investigate\n\nUse the scan output to answer questions for each of the seven templates. Load [`references/inquiry-checkpoints.md`](references/inquiry-checkpoints.md) for the full per-template question list.\n\nIf the stack is ambiguous (multiple manifest files, unfamiliar file types, no `package.json`), load [`references/stack-detection.md`](references/stack-detection.md).\n\n### Phase 3: Populate Templates\n\nCopy each template from `assets/templates/` into `docs/codebase/`. Fill in this order:\n\n1. [STACK.md](assets/templates/STACK.md) — language, runtime, frameworks, all dependencies\n2. [STRUCTURE.md](assets/templates/STRUCTURE.md) — directory layout, entry points, key files\n3. [ARCHITECTURE.md](assets/templates/ARCHITECTURE.md) — layers, patterns, data flow\n4. [CONVENTIONS.md](assets/templates/CONVENTIONS.md) — naming, formatting, error handling, imports\n5. [INTEGRATIONS.md](assets/templates/INTEGRATIONS.md) — external APIs, databases, auth, monitoring\n6. [TESTING.md](assets/templates/TESTING.md) — frameworks, file organization, mocking strategy\n7. [CONCERNS.md](assets/templates/CONCERNS.md) — tech debt, bugs, security risks, perf bottlenecks\n\nUse `[TODO]` for anything that cannot be determined from code. Use `[ASK USER]` where the right answer requires team intent.\n\n### Phase 4: Validate, Repair, Verify\n\nRun this mandatory validation loop before finalizing:\n\n1. Validate each doc against `references/inquiry-checkpoints.md`.\n2. For each non-trivial claim, confirm at least one evidence reference exists.\n3. If any required section is missing or unsupported:\n  - Fix the document.\n  - Re-run validation.\n4. Repeat until all seven docs pass.\n\nThen present a summary of all seven documents, list every `[ASK USER]` item as a numbered question, and highlight any Intent vs. Reality divergences from Phase 1.\n\nValidation pass criteria:\n\n- No unsupported claims.\n- No empty required sections.\n- Unknowns use `[TODO]` rather than assumptions.\n- Team-intent gaps are explicitly marked `[ASK USER]`.\n\n---\n\n## Gotchas\n\n**Monorepos:** Root `package.json` may have no source — check for `workspaces`, `packages/`, or `apps/` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.\n\n**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.\n\n**TypeScript path aliases:** `tsconfig.json` `paths` config means imports like `@/foo` don't map directly to the filesystem. Map aliases to real paths before documenting structure.\n\n**Generated/compiled output:** Never document patterns from `dist/`, `build/`, `generated/`, `.next/`, `out/`, or `__pycache__/`. These are artefacts — document source conventions only.\n\n**`.env.example` reveals required config:** Secrets are never committed. Read `.env.example`, `.env.template`, or `.env.sample` to discover required environment variables.\n\n**`devDependencies` ≠ production stack:** Only `dependencies` (or equivalent, e.g. `[tool.poetry.dependencies]`) runs in production. Document linters, formatters, and test frameworks separately as dev tooling.\n\n**Test TODOs ≠ production debt:** TODOs inside `test/`, `tests/`, `__tests__/`, or `spec/` are coverage gaps, not production technical debt. Separate them in `CONCERNS.md`.\n\n**High-churn files = fragile areas:** Files appearing most in recent git history have the highest modification rate and likely hidden complexity. Always note them in `CONCERNS.md`.\n\n---\n\n## Anti-Patterns\n\n| ❌ Don't | ✅ Do instead |\n|---------|--------------|\n| \"Uses Clean Architecture with Domain/Data layers.\" (when no such directories exist) | State only what directory structure actually shows. |\n| \"This is a Next.js project.\" (without checking `package.json`) | Check `dependencies` first. State what's actually there. |\n| Guess the database from a variable name like `dbUrl` | Check manifest for `pg`, `mysql2`, `mongoose`, `prisma`, etc. |\n| Document `dist/` or `build/` naming patterns as conventions | Source files only. |\n\n---\n\n## Enhanced Scan Output Sections\n\nThe `scan.py` script now produce the following sections in addition to the original output:\n\n- **CODE METRICS** — Total files, lines of code by language, largest files (complexity signals)\n- **CI/CD PIPELINES** — Detected GitHub Actions, GitLab CI, Jenkins, CircleCI, etc.\n- **CONTAINERS \u0026 ORCHESTRATION** — Docker, Docker Compose, Kubernetes, Vagrant configs\n- **SECURITY \u0026 COMPLIANCE** — Snyk, Dependabot, SECURITY.md, SBOM, security policies\n- **PERFORMANCE \u0026 TESTING** — Benchmark configs, profiling markers, load testing tools\n\nUse these sections during Phase 2 to inform investigation questions and identify tool-specific patterns.\n\n---\n\n## Bundled Assets\n\n| Asset | When to load |\n|-------|-------------|\n| [`scripts/scan.py`](scripts/scan.py) | Phase 1 — run first, before reading any code (Python 3.8+ required) |\n\n| [`references/inquiry-checkpoints.md`](references/inquiry-checkpoints.md) | Phase 2 — load for per-template investigation questions |\n| [`references/stack-detection.md`](references/stack-detection.md) | Phase 2 — only if stack is ambiguous |\n| [`assets/templates/STACK.md`](assets/templates/STACK.md) | Phase 3 step 1 |\n| [`assets/templates/STRUCTURE.md`](assets/templates/STRUCTURE.md) | Phase 3 step 2 |\n| [`assets/templates/ARCHITECTURE.md`](assets/templates/ARCHITECTURE.md) | Phase 3 step 3 |\n| [`assets/templates/CONVENTIONS.md`](assets/templates/CONVENTIONS.md) | Phase 3 step 4 |\n| [`assets/templates/INTEGRATIONS.md`](assets/templates/INTEGRATIONS.md) | Phase 3 step 5 |\n| [`assets/templates/TESTING.md`](assets/templates/TESTING.md) | Phase 3 step 6 |\n| [`assets/templates/CONCERNS.md`](assets/templates/CONCERNS.md) | Phase 3 step 7 |\n\nTemplate usage mode:\n\n- Default mode: complete only the \"Core Sections (Required)\" in each template.\n- Extended mode: add optional sections only when the repo complexity justifies them.\n","assets/templates/ARCHITECTURE.md":"# Architecture\n\n## Core Sections (Required)\n\n### 1) Architectural Style\n\n- Primary style: [layered/feature/event-driven/other]\n- Why this classification: [short evidence-backed rationale]\n- Primary constraints: [2-3 constraints that shape design]\n\n### 2) System Flow\n\n```text\n[entry] -\u003e [processing] -\u003e [domain logic] -\u003e [data/integration] -\u003e [response/output]\n```\n\nDescribe the flow in 4-6 steps using file-backed evidence.\n\n### 3) Layer/Module Responsibilities\n\n| Layer or module | Owns | Must not own | Evidence |\n|-----------------|------|--------------|----------|\n| [name] | [responsibility] | [non-responsibility] | [file] |\n\n### 4) Reused Patterns\n\n| Pattern | Where found | Why it exists |\n|---------|-------------|---------------|\n| [singleton/repository/adapter/etc] | [path] | [reason] |\n\n### 5) Known Architectural Risks\n\n- [Risk 1 + impact]\n- [Risk 2 + impact]\n\n### 6) Evidence\n\n- [path/to/entrypoint]\n- [path/to/main-layer-files]\n- [path/to/data-or-integration-layer]\n\n## Extended Sections (Optional)\n\nAdd only when needed:\n\n- Startup or initialization order details\n- Async/event topology diagrams\n- Anti-pattern catalog with refactoring paths\n- Failure-mode analysis and resilience posture\n","assets/templates/CONCERNS.md":"# Codebase Concerns\n\n## Core Sections (Required)\n\n### 1) Top Risks (Prioritized)\n\n| Severity | Concern | Evidence | Impact | Suggested action |\n|----------|---------|----------|--------|------------------|\n| [high/med/low] | [issue] | [file or scan output] | [impact] | [next action] |\n\n### 2) Technical Debt\n\nList the most important debt items only.\n\n| Debt item | Why it exists | Where | Risk if ignored | Suggested fix |\n|-----------|---------------|-------|-----------------|---------------|\n| [item] | [reason] | [path] | [risk] | [fix] |\n\n### 3) Security Concerns\n\n| Risk | OWASP category (if applicable) | Evidence | Current mitigation | Gap |\n|------|--------------------------------|----------|--------------------|-----|\n| [risk] | [A01/A03/etc or N/A] | [path] | [what exists] | [what is missing] |\n\n### 4) Performance and Scaling Concerns\n\n| Concern | Evidence | Current symptom | Scaling risk | Suggested improvement |\n|---------|----------|-----------------|-------------|-----------------------|\n| [issue] | [path/metric] | [symptom] | [risk] | [action] |\n\n### 5) Fragile/High-Churn Areas\n\n| Area | Why fragile | Churn signal | Safe change strategy |\n|------|-------------|-------------|----------------------|\n| [path] | [reason] | [recent churn evidence] | [approach] |\n\n### 6) `[ASK USER]` Questions\n\nAdd unresolved intent-dependent questions as a numbered list.\n\n1. [ASK USER] [question]\n\n### 7) Evidence\n\n- [scan output section reference]\n- [path/to/code-file]\n- [path/to/config-or-history-evidence]\n\n## Extended Sections (Optional)\n\nAdd only when needed:\n\n- Full bug inventory\n- Component-level remediation roadmap\n- Cost/effort estimates by concern\n- Dependency-risk and ownership mapping\n","assets/templates/CONVENTIONS.md":"# Coding Conventions\n\n## Core Sections (Required)\n\n### 1) Naming Rules\n\n| Item | Rule | Example | Evidence |\n|------|------|---------|----------|\n| Files | [RULE] | [EXAMPLE] | [FILE] |\n| Functions/methods | [RULE] | [EXAMPLE] | [FILE] |\n| Types/interfaces | [RULE] | [EXAMPLE] | [FILE] |\n| Constants/env vars | [RULE] | [EXAMPLE] | [FILE] |\n\n### 2) Formatting and Linting\n\n- Formatter: [TOOL + CONFIG FILE]\n- Linter: [TOOL + CONFIG FILE]\n- Most relevant enforced rules: [RULE_1], [RULE_2], [RULE_3]\n- Run commands: [COMMANDS]\n\n### 3) Import and Module Conventions\n\n- Import grouping/order: [RULE]\n- Alias vs relative import policy: [RULE]\n- Public exports/barrel policy: [RULE]\n\n### 4) Error and Logging Conventions\n\n- Error strategy by layer: [SHORT SUMMARY]\n- Logging style and required context fields: [SUMMARY]\n- Sensitive-data redaction rules: [SUMMARY]\n\n### 5) Testing Conventions\n\n- Test file naming/location rule: [RULE]\n- Mocking strategy norm: [RULE]\n- Coverage expectation: [RULE or TODO]\n\n### 6) Evidence\n\n- [path/to/lint-config]\n- [path/to/format-config]\n- [path/to/representative-source-file]\n\n## Extended Sections (Optional)\n\nAdd only for large or inconsistent codebases:\n\n- Layer-specific error handling matrix\n- Language-specific strictness options\n- Repo-specific commit/branching conventions\n- Known convention violations to clean up\n","assets/templates/INTEGRATIONS.md":"# External Integrations\n\n## Core Sections (Required)\n\n### 1) Integration Inventory\n\n| System | Type (API/DB/Queue/etc) | Purpose | Auth model | Criticality | Evidence |\n|--------|---------------------------|---------|------------|-------------|----------|\n| [name] | [type] | [purpose] | [auth] | [high/med/low] | [file] |\n\n### 2) Data Stores\n\n| Store | Role | Access layer | Key risk | Evidence |\n|-------|------|--------------|----------|----------|\n| [db/cache/etc] | [role] | [module] | [risk] | [file] |\n\n### 3) Secrets and Credentials Handling\n\n- Credential sources: [env/secrets manager/config]\n- Hardcoding checks: [result]\n- Rotation or lifecycle notes: [known/unknown]\n\n### 4) Reliability and Failure Behavior\n\n- Retry/backoff behavior: [implemented/none/partial]\n- Timeout policy: [where configured]\n- Circuit-breaker or fallback behavior: [if any]\n\n### 5) Observability for Integrations\n\n- Logging around external calls: [yes/no + where]\n- Metrics/tracing coverage: [yes/no + where]\n- Missing visibility gaps: [list]\n\n### 6) Evidence\n\n- [path/to/integration-wrapper]\n- [path/to/config-or-env-template]\n- [path/to/monitoring-or-logging-config]\n\n## Extended Sections (Optional)\n\nAdd only when needed:\n\n- Endpoint-by-endpoint catalog\n- Auth flow sequence diagrams\n- SLA/SLO per integration\n- Region/failover topology notes\n","assets/templates/STACK.md":"# Technology Stack\n\n## Core Sections (Required)\n\n### 1) Runtime Summary\n\n| Area | Value | Evidence |\n|------|-------|----------|\n| Primary language | [VALUE] | [FILE_PATH] |\n| Runtime + version | [VALUE] | [FILE_PATH] |\n| Package manager | [VALUE] | [FILE_PATH] |\n| Module/build system | [VALUE] | [FILE_PATH] |\n\n### 2) Production Frameworks and Dependencies\n\nList only high-impact production dependencies (frameworks, data, transport, auth).\n\n| Dependency | Version | Role in system | Evidence |\n|------------|---------|----------------|----------|\n| [NAME] | [VERSION] | [ROLE] | [FILE_PATH] |\n\n### 3) Development Toolchain\n\n| Tool | Purpose | Evidence |\n|------|---------|----------|\n| [TOOL] | [LINT/FORMAT/TEST/BUILD] | [FILE_PATH] |\n\n### 4) Key Commands\n\n```bash\n[install command]\n[build command]\n[test command]\n[lint command]\n```\n\n### 5) Environment and Config\n\n- Config sources: [LIST FILES]\n- Required env vars: [VAR_1], [VAR_2], [TODO]\n- Deployment/runtime constraints: [SHORT NOTE]\n\n### 6) Evidence\n\n- [path/to/manifest]\n- [path/to/runtime-config]\n- [path/to/build-or-ci-config]\n\n## Extended Sections (Optional)\n\nAdd only when needed for complex repos:\n\n- Full dependency taxonomy by category\n- Detailed compiler/runtime flags\n- Environment matrix (dev/stage/prod)\n- Process manager and container runtime details\n","assets/templates/STRUCTURE.md":"# Codebase Structure\n\n## Core Sections (Required)\n\n### 1) Top-Level Map\n\nList only meaningful top-level directories and files.\n\n| Path | Purpose | Evidence |\n|------|---------|----------|\n| [path/] | [purpose] | [source] |\n\n### 2) Entry Points\n\n- Main runtime entry: [FILE]\n- Secondary entry points (worker/cli/jobs): [FILES or NONE]\n- How entry is selected (script/config): [NOTE]\n\n### 3) Module Boundaries\n\n| Boundary | What belongs here | What must not be here |\n|----------|-------------------|------------------------|\n| [module/layer] | [responsibility] | [forbidden logic] |\n\n### 4) Naming and Organization Rules\n\n- File naming pattern: [kebab/camel/Pascal + examples]\n- Directory organization pattern: [feature/layer/domain]\n- Import aliasing or path conventions: [RULE]\n\n### 5) Evidence\n\n- [path/to/root-tree-source]\n- [path/to/entry-config]\n- [path/to/key-module]\n\n## Extended Sections (Optional)\n\nAdd only when repository complexity requires it:\n\n- Subdirectory deep maps by feature/layer\n- Middleware/boot order details\n- Generated-vs-source layout boundaries\n- Monorepo workspace-level structure maps\n","assets/templates/TESTING.md":"# Testing Patterns\n\n## Core Sections (Required)\n\n### 1) Test Stack and Commands\n\n- Primary test framework: [NAME + VERSION]\n- Assertion/mocking tools: [TOOLS]\n- Commands:\n\n```bash\n[run all tests]\n[run unit tests]\n[run integration/e2e tests]\n[run coverage]\n```\n\n### 2) Test Layout\n\n- Test file placement pattern: [co-located/tests folder/etc]\n- Naming convention: [pattern]\n- Setup files and where they run: [paths]\n\n### 3) Test Scope Matrix\n\n| Scope | Covered? | Typical target | Notes |\n|-------|----------|----------------|-------|\n| Unit | [yes/no] | [modules/services] | [notes] |\n| Integration | [yes/no] | [API/data boundaries] | [notes] |\n| E2E | [yes/no] | [user flows] | [notes] |\n\n### 4) Mocking and Isolation Strategy\n\n- Main mocking approach: [module/class/network]\n- Isolation guarantees: [what is reset and when]\n- Common failure mode in tests: [short note]\n\n### 5) Coverage and Quality Signals\n\n- Coverage tool + threshold: [value or TODO]\n- Current reported coverage: [value or TODO]\n- Known gaps/flaky areas: [list]\n\n### 6) Evidence\n\n- [path/to/test-config]\n- [path/to/representative-test-file]\n- [path/to/ci-or-coverage-config]\n\n## Extended Sections (Optional)\n\nAdd only when needed:\n\n- Framework-specific suite patterns\n- Detailed mock recipes per dependency type\n- Historical flaky test catalog\n- Test performance bottlenecks and optimization ideas\n","references/inquiry-checkpoints.md":"# Inquiry Checkpoints\n\nPer-template investigation questions for Phase 2 of the acquire-codebase-knowledge workflow. For each template area, look for answers in the scan output first, then read source files to fill gaps.\n\n---\n\n## 1. STACK.md — Tech Stack\n\n- What is the primary language and exact version? (check `.nvmrc`, `go.mod`, `pyproject.toml`, Docker `FROM` line)\n- What package manager is used? (`npm`, `yarn`, `pnpm`, `go mod`, `pip`, `uv`)\n- What are the core runtime frameworks? (web server, ORM, DI container)\n- What do `dependencies` (production) vs `devDependencies` (dev tooling) contain?\n- Is there a Docker image and what base image does it use?\n- What are the key scripts in `package.json` / `Makefile` / `pyproject.toml`?\n\n## 2. STRUCTURE.md — Directory Layout\n\n- Where does source code live? (usually `src/`, `lib/`, or project root for Go)\n- What are the entry points? (check `main` in `package.json`, `scripts.start`, `cmd/main.go`, `app.py`)\n- What is the stated purpose of each top-level directory?\n- Are there non-obvious directories (e.g., `eng/`, `platform/`, `infra/`)?\n- Are there hidden config directories (`.github/`, `.vscode/`, `.husky/`)?\n- What naming conventions do directories follow? (camelCase, kebab-case, domain-based vs layer-based)\n\n## 3. ARCHITECTURE.md — Patterns\n\n- Is the code organized by layer (controllers → services → repos) or by feature?\n- What is the primary data flow? Trace one request or command from entry to data store.\n- Are there singletons, dependency injection patterns, or explicit initialization order requirements?\n- Are there background workers, queues, or event-driven components?\n- What design patterns appear repeatedly? (Factory, Repository, Decorator, Strategy)\n\n## 4. CONVENTIONS.md — Coding Standards\n\n- What is the file naming convention? (check 10+ files — camelCase, kebab-case, PascalCase)\n- What is the function and variable naming convention?\n- Are private methods/fields prefixed (e.g., `_methodName`, `#field`)?\n- What linter and formatter are configured? (check `.eslintrc`, `.prettierrc`, `golangci.yml`)\n- What are the TypeScript strictness settings? (`strict`, `noImplicitAny`, etc.)\n- How are errors handled at each layer? (throw vs. return structured error)\n- What logging library is used and what is the log message format?\n- How are imports organized? (barrel exports, path aliases, grouping rules)\n\n## 5. INTEGRATIONS.md — External Services\n\n- What external APIs are called? (search for `axios.`, `fetch(`, `http.Get(`, base URLs in constants)\n- How are credentials stored and accessed? (`.env`, secrets manager, env vars)\n- What databases are connected? (check manifest for `pg`, `mongoose`, `prisma`, `typeorm`, `sqlalchemy`)\n- Is there an API gateway, service mesh, or proxy between the app and external services?\n- What monitoring or observability tools are used? (APM, Prometheus, logging pipeline)\n- Are there message queues or event buses? (Kafka, RabbitMQ, SQS, Pub/Sub)\n\n## 6. TESTING.md — Test Setup\n\n- What test runner is configured? (check `scripts.test` in `package.json`, `pytest.ini`, `go test`)\n- Where are test files located? (alongside source, in `tests/`, in `__tests__/`)\n- What assertion library is used? (Jest expect, Chai, pytest assert)\n- How are external dependencies mocked? (jest.mock, dependency injection, fixtures)\n- Are there integration tests that hit real services vs. unit tests with mocks?\n- Is there a coverage threshold enforced? (check `jest.config.js`, `.nycrc`, `pyproject.toml`)\n\n## 7. CONCERNS.md — Known Issues\n\n- How many TODOs/FIXMEs/HACKs are in production code? (see scan output)\n- Which files have the highest git churn in the last 90 days? (see scan output)\n- Are there any files over 500 lines that mix multiple responsibilities?\n- Do any services make sequential calls that could be parallelized?\n- Are there hardcoded values (URLs, IDs, magic numbers) that should be config?\n- What security risks exist? (missing input validation, raw error messages exposed to clients, missing auth checks)\n- Are there performance patterns that don't scale? (N+1 queries, in-memory caches in multi-instance setups)\n","references/stack-detection.md":"# Stack Detection Reference\n\nLoad this file when the tech stack is ambiguous — e.g., multiple manifest files present, unfamiliar file extensions, or no obvious `package.json` / `go.mod`.\n\n---\n\n## Manifest File → Ecosystem\n\n| File | Ecosystem | Key fields to read |\n|------|-----------|--------------------|\n| `package.json` | Node.js / JavaScript / TypeScript | `dependencies`, `devDependencies`, `scripts`, `main`, `type`, `engines` |\n| `go.mod` | Go | Module path, Go version, `require` block |\n| `requirements.txt` | Python (pip) | Package list with pinned versions |\n| `Pipfile` | Python (pipenv) | `[packages]`, `[dev-packages]`, `[requires]` python version |\n| `pyproject.toml` | Python (poetry / uv / hatch) | `[tool.poetry.dependencies]`, `[project]`, `[build-system]` |\n| `setup.py` / `setup.cfg` | Python (setuptools, legacy) | `install_requires`, `python_requires` |\n| `Cargo.toml` | Rust | `[dependencies]`, `[[bin]]`, `[lib]` |\n| `pom.xml` | Java / Kotlin (Maven) | `\u003cdependencies\u003e`, `\u003cartifactId\u003e`, `\u003cgroupId\u003e`, `\u003cjava.version\u003e` |\n| `build.gradle` / `build.gradle.kts` | Java / Kotlin (Gradle) | `dependencies {}`, `sourceCompatibility` |\n| `composer.json` | PHP | `require`, `require-dev` |\n| `Gemfile` | Ruby | `gem` declarations, `ruby` version constraint |\n| `mix.exs` | Elixir | `deps/0`, `elixir: \"~\u003e X.Y\"` |\n| `pubspec.yaml` | Dart / Flutter | `dependencies`, `dev_dependencies`, `environment.sdk` |\n| `*.csproj` | .NET / C# | `\u003cPackageReference\u003e`, `\u003cTargetFramework\u003e` |\n| `*.sln` | .NET solution | References multiple `.csproj` projects |\n| `deno.json` / `deno.jsonc` | Deno (TypeScript runtime) | `imports`, `tasks` |\n| `bun.lockb` | Bun (JavaScript runtime) | Binary lockfile — check `package.json` for deps |\n\n---\n\n## Language Runtime Version Detection\n\n| Language | Where to find the version |\n|----------|--------------------------|\n| Node.js | `.nvmrc`, `.node-version`, `engines.node` in `package.json`, Docker `FROM node:X` |\n| Python | `.python-version`, `pyproject.toml [requires-python]`, Docker `FROM python:X` |\n| Go | First line of `go.mod` (`go 1.21`) |\n| Java | `\u003cjava.version\u003e` in `pom.xml`, `sourceCompatibility` in `build.gradle`, Docker `FROM eclipse-temurin:X` |\n| Ruby | `.ruby-version`, `Gemfile` `ruby 'X.Y.Z'` |\n| Rust | `rust-toolchain.toml`, `rust-toolchain` file |\n| .NET | `\u003cTargetFramework\u003e` in `.csproj` (e.g., `net8.0`) |\n\n---\n\n## Framework Detection (Node.js / TypeScript)\n\n| Dependency in `package.json` | Framework |\n|-----------------------------|-----------|\n| `express` | Express.js (minimal HTTP server) |\n| `fastify` | Fastify (high-performance HTTP server) |\n| `next` | Next.js (SSR/SSG React — check for `pages/` or `app/` directory) |\n| `nuxt` | Nuxt.js (SSR/SSG Vue) |\n| `@nestjs/core` | NestJS (opinionated Node.js framework with DI) |\n| `koa` | Koa (middleware-focused, no built-in router) |\n| `@hapi/hapi` | Hapi |\n| `@trpc/server` | tRPC (type-safe API without REST/GraphQL schemas) |\n| `routing-controllers` | routing-controllers (decorator-based Express wrapper) |\n| `typeorm` | TypeORM (SQL ORM with decorators) |\n| `prisma` | Prisma (type-safe ORM, check `prisma/schema.prisma`) |\n| `mongoose` | Mongoose (MongoDB ODM) |\n| `sequelize` | Sequelize (SQL ORM) |\n| `drizzle-orm` | Drizzle (lightweight SQL ORM) |\n| `react` without `next` | Vanilla React SPA (check for `react-router-dom`) |\n| `vue` without `nuxt` | Vanilla Vue SPA |\n\n---\n\n## Framework Detection (Python)\n\n| Package | Framework |\n|---------|-----------|\n| `fastapi` | FastAPI (async REST, auto OpenAPI docs) |\n| `flask` | Flask (minimal WSGI web framework) |\n| `django` | Django (batteries-included, check `settings.py`) |\n| `starlette` | Starlette (ASGI, often used as FastAPI base) |\n| `aiohttp` | aiohttp (async HTTP client and server) |\n| `sqlalchemy` | SQLAlchemy (SQL ORM; check for `alembic` migrations) |\n| `alembic` | Alembic (SQLAlchemy migration tool) |\n| `pydantic` | Pydantic (data validation; core to FastAPI) |\n| `celery` | Celery (distributed task queue) |\n\n---\n\n## Monorepo Detection\n\nCheck these signals in order:\n\n1. `pnpm-workspace.yaml` — pnpm workspaces\n2. `lerna.json` — Lerna monorepo\n3. `nx.json` — Nx monorepo (also check `workspace.json`)\n4. `turbo.json` — Turborepo\n5. `rush.json` — Rush (Microsoft monorepo manager)\n6. `moon.yml` — Moon\n7. `package.json` with `\"workspaces\": [...]` — npm/yarn workspaces\n8. Presence of `packages/`, `apps/`, `libs/`, or `services/` directories with their own `package.json`\n\nIf monorepo is detected: each workspace may have **independent** dependencies and conventions. Map each sub-package separately in `STACK.md` and note the monorepo structure in `STRUCTURE.md`.\n\n---\n\n## TypeScript Path Alias Detection\n\nIf `tsconfig.json` has a `paths` key, imports with non-relative prefixes are aliases. Map them before documenting structure.\n\n```json\n// tsconfig.json example\n\"paths\": {\n  \"@/*\": [\"./src/*\"],\n  \"@components/*\": [\"./src/components/*\"],\n  \"@utils/*\": [\"./src/utils/*\"]\n}\n```\n\nImports like `import { foo } from '@/utils/bar'` resolve to `src/utils/bar`. Document as `src/utils/bar`, not `@/utils/bar`.\n\n---\n\n## Docker Base Image → Runtime\n\nIf no manifest file is present but a `Dockerfile` exists, the `FROM` line reveals the runtime:\n\n| FROM line pattern | Runtime |\n|------------------|---------|\n| `FROM node:X` | Node.js X |\n| `FROM python:X` | Python X |\n| `FROM golang:X` | Go X |\n| `FROM eclipse-temurin:X` | Java X (Eclipse Temurin JDK) |\n| `FROM mcr.microsoft.com/dotnet/aspnet:X` | .NET X |\n| `FROM ruby:X` | Ruby X |\n| `FROM rust:X` | Rust X |\n| `FROM alpine` (alone) | Check what's installed via `RUN apk add` |\n","scripts/scan.py":"#!/usr/bin/env python3\n\"\"\"\nscan.py — Collect project discovery information for the acquire-codebase-knowledge skill.\nRun from the project root directory.\n\nUsage: python3 scan.py [OPTIONS]\n\nOptions:\n  --output FILE   Write output to FILE instead of stdout\n  --help          Show this message and exit\n\nExit codes:\n  0  Success\n  1  Usage error\n\"\"\"\n\nimport os\nimport sys\nimport argparse\nimport subprocess\nimport json\nfrom pathlib import Path\nfrom typing import List, Set\nimport re\n\nTREE_LIMIT = 200\nTREE_MAX_DEPTH = 3\nTODO_LIMIT = 60\nMANIFEST_PREVIEW_LINES = 80\nRECENT_COMMITS_LIMIT = 20\nCHURN_LIMIT = 20\n\nEXCLUDE_DIRS = {\n    \"node_modules\", \".git\", \"dist\", \"build\", \"out\", \".next\", \".nuxt\",\n    \"__pycache__\", \".venv\", \"venv\", \".tox\", \"target\", \"vendor\",\n    \"coverage\", \".nyc_output\", \"generated\", \".cache\", \".turbo\",\n    \".yarn\", \".pnp\", \"bin\", \"obj\"\n}\n\nMANIFESTS = [\n    # JavaScript/Node.js\n    \"package.json\", \"package-lock.json\", \"yarn.lock\", \"pnpm-lock.yaml\", \"bun.lockb\",\n    \"deno.json\", \"deno.jsonc\",\n    # Python\n    \"requirements.txt\", \"Pipfile\", \"Pipfile.lock\", \"pyproject.toml\", \"setup.py\", \"setup.cfg\",\n    \"poetry.lock\", \"pdm.lock\", \"uv.lock\",\n    # Go\n    \"go.mod\", \"go.sum\",\n    # Rust\n    \"Cargo.toml\", \"Cargo.lock\",\n    # Java/Kotlin\n    \"pom.xml\", \"build.gradle\", \"build.gradle.kts\", \"settings.gradle\", \"settings.gradle.kts\",\n    \"gradle.properties\",\n    # PHP/Composer\n    \"composer.json\", \"composer.lock\",\n    # Ruby\n    \"Gemfile\", \"Gemfile.lock\", \"*.gemspec\",\n    # Elixir\n    \"mix.exs\", \"mix.lock\",\n    # Dart/Flutter\n    \"pubspec.yaml\", \"pubspec.lock\",\n    # .NET/C#\n    \"*.csproj\", \"*.sln\", \"*.slnx\", \"global.json\", \"packages.config\",\n    # Swift\n    \"Package.swift\", \"Package.resolved\",\n    # Scala\n    \"build.sbt\", \"scala-cli.yml\",\n    # Haskell\n    \"*.cabal\", \"stack.yaml\", \"cabal.project\", \"cabal.project.local\",\n    # OCaml\n    \"dune-project\", \"opam\", \"opam.lock\",\n    # Nim\n    \"*.nimble\", \"nim.cfg\",\n    # Crystal\n    \"shard.yml\", \"shard.lock\",\n    # R\n    \"DESCRIPTION\", \"renv.lock\",\n    # Julia\n    \"Project.toml\", \"Manifest.toml\",\n    # Build systems\n    \"CMakeLists.txt\", \"Makefile\", \"GNUmakefile\",\n    \"SConstruct\", \"build.xml\",\n    \"BUILD\", \"BUILD.bazel\", \"WORKSPACE\", \"bazel.lock\",\n    \"justfile\", \".justfile\", \"Taskfile.yml\",\n    \"tox.ini\", \"Vagrantfile\"\n]\n\nENTRY_CANDIDATES = [\n    # JavaScript/Node.js/TypeScript\n    \"src/index.ts\", \"src/index.js\", \"src/index.mjs\",\n    \"src/main.ts\", \"src/main.js\", \"src/main.py\",\n    \"src/app.ts\", \"src/app.js\",\n    \"src/server.ts\", \"src/server.js\",\n    \"index.ts\", \"index.js\", \"app.ts\", \"app.js\",\n    \"lib/index.ts\", \"lib/index.js\",\n    # Go\n    \"main.go\", \"cmd/main.go\", \"cmd/*/main.go\",\n    # Python\n    \"main.py\", \"app.py\", \"server.py\", \"run.py\", \"cli.py\",\n    \"src/main.py\", \"src/__main__.py\",\n    # .NET/C#\n    \"Program.cs\", \"src/Program.cs\", \"Main.cs\",\n    # Java\n    \"Main.java\", \"Application.java\", \"App.java\",\n    \"src/main/java/Main.java\",\n    # Kotlin\n    \"Main.kt\", \"Application.kt\", \"App.kt\",\n    # Rust\n    \"src/main.rs\", \"src/lib.rs\",\n    # Swift\n    \"main.swift\", \"Package.swift\", \"Sources/main.swift\",\n    # Ruby\n    \"app.rb\", \"main.rb\", \"lib/app.rb\",\n    # PHP\n    \"index.php\", \"app.php\", \"public/index.php\",\n    # Go\n    \"cmd/*/main.go\",\n    # Scala\n    \"src/main/scala/Main.scala\",\n    # Haskell\n    \"Main.hs\", \"app/Main.hs\",\n    # Clojure\n    \"src/core.clj\", \"-main.clj\",\n    # Elixir\n    \"lib/application.ex\", \"mix.exs\",\n]\n\nLINT_FILES = [\n    \".eslintrc\", \".eslintrc.json\", \".eslintrc.js\", \".eslintrc.cjs\", \".eslintrc.yml\", \".eslintrc.yaml\",\n    \"eslint.config.js\", \"eslint.config.mjs\", \"eslint.config.cjs\",\n    \".prettierrc\", \".prettierrc.json\", \".prettierrc.js\", \".prettierrc.yml\",\n    \"prettier.config.js\", \"prettier.config.mjs\",\n    \".editorconfig\",\n    \"tsconfig.json\", \"tsconfig.base.json\", \"tsconfig.build.json\",\n    \".golangci.yml\", \".golangci.yaml\",\n    \"setup.cfg\", \".flake8\", \".pylintrc\", \"mypy.ini\",\n    \".rubocop.yml\", \"phpcs.xml\", \"phpstan.neon\",\n    \"biome.json\", \"biome.jsonc\"\n]\n\nENV_TEMPLATES = [\".env.example\", \".env.template\", \".env.sample\", \".env.defaults\", \".env.local.example\"]\n\nSOURCE_EXTS = [\n    \"ts\", \"tsx\", \"js\", \"jsx\", \"mjs\", \"cjs\",\n    \"py\", \"go\", \"java\", \"kt\", \"rb\", \"php\",\n    \"rs\", \"cs\", \"cpp\", \"c\", \"h\", \"ex\", \"exs\",\n    \"swift\", \"scala\", \"clj\", \"cljs\", \"lua\",\n    \"vim\", \"vim\", \"hs\", \"ml\", \"ml\", \"nim\", \"cr\",\n    \"r\", \"jl\", \"groovy\", \"gradle\", \"xml\", \"json\"\n]\n\nMONOREPO_FILES = [\"pnpm-workspace.yaml\", \"lerna.json\", \"nx.json\", \"rush.json\", \"turbo.json\", \"moon.yml\"]\nMONOREPO_DIRS = [\"packages\", \"apps\", \"libs\", \"services\", \"modules\"]\n\nCI_CD_CONFIGS = {\n    \".github/workflows\": \"GitHub Actions\",\n    \".gitlab-ci.yml\": \"GitLab CI\",\n    \"Jenkinsfile\": \"Jenkins\",\n    \".circleci/config.yml\": \"CircleCI\",\n    \".travis.yml\": \"Travis CI\",\n    \"azure-pipelines.yml\": \"Azure Pipelines\",\n    \"appveyor.yml\": \"AppVeyor\",\n    \".drone.yml\": \"Drone CI\",\n    \".woodpecker.yml\": \"Woodpecker CI\",\n    \"bitbucket-pipelines.yml\": \"Bitbucket Pipelines\"\n}\n\nCONTAINER_FILES = [\n    \"Dockerfile\", \"docker-compose.yml\", \"docker-compose.yaml\",\n    \".dockerignore\", \"Dockerfile.*\",\n    \"k8s\", \"kustomization.yaml\", \"Chart.yaml\",\n    \"Vagrantfile\", \"podman-compose.yml\"\n]\n\nSECURITY_CONFIGS = [\n    \".snyk\", \"security.txt\", \"SECURITY.md\",\n    \".dependabot.yml\", \".whitesource\",\n    \"sbom.json\", \"sbom.spdx\", \".bandit.yaml\"\n]\n\nPERFORMANCE_MARKERS = [\n    \"benchmark\", \"bench\", \"perf.data\", \".prof\",\n    \"k6.js\", \"locustfile.py\", \"jmeter.jmx\"\n]\n\n\ndef parse_args():\n    \"\"\"Parse command-line arguments.\"\"\"\n    parser = argparse.ArgumentParser(\n        description=\"Scan the current directory (project root) and output discovery information \"\n                    \"for the acquire-codebase-knowledge skill.\",\n        add_help=True\n    )\n    parser.add_argument(\n        \"--output\",\n        type=str,\n        help=\"Write output to FILE instead of stdout\"\n    )\n    return parser.parse_args()\n\n\ndef should_exclude(path: Path) -\u003e bool:\n    \"\"\"Check if a path should be excluded from scanning.\"\"\"\n    return any(part in EXCLUDE_DIRS for part in path.parts)\n\n\ndef get_directory_tree(max_depth: int = TREE_MAX_DEPTH) -\u003e List[str]:\n    \"\"\"Get directory tree up to max_depth.\"\"\"\n    files = []\n\n    def walk(path: Path, depth: int):\n        if depth \u003e max_depth or should_exclude(path):\n            return\n        try:\n            for item in sorted(path.iterdir()):\n                if should_exclude(item):\n                    continue\n                rel_path = item.relative_to(Path.cwd())\n                files.append(str(rel_path))\n                if item.is_dir():\n                    walk(item, depth + 1)\n        except (PermissionError, OSError):\n            pass\n\n    walk(Path.cwd(), 0)\n    return files[:TREE_LIMIT]\n\n\ndef find_manifest_files() -\u003e List[str]:\n    \"\"\"Find manifest files matching patterns.\"\"\"\n    found = []\n    for pattern in MANIFESTS:\n        if \"*\" in pattern:\n            # Handle glob patterns\n            for path in Path.cwd().glob(pattern):\n                if path.is_file() and not should_exclude(path):\n                    found.append(path.name)\n        else:\n            path = Path.cwd() / pattern\n            if path.is_file():\n                found.append(pattern)\n    return sorted(set(found))\n\n\ndef read_file_preview(filepath: Path, max_lines: int = MANIFEST_PREVIEW_LINES) -\u003e str:\n    \"\"\"Read file with line limit.\"\"\"\n    try:\n        with open(filepath, 'r', encoding='utf-8', errors='replace') as f:\n            lines = f.readlines()\n\n        if not lines:\n            return \"None found.\"\n\n        preview = ''.join(lines[:max_lines])\n        if len(lines) \u003e max_lines:\n            preview += f\"\\n[TRUNCATED] Showing first {max_lines} of {len(lines)} lines.\"\n        return preview\n    except Exception as e:\n        return f\"[Error reading file: {e}]\"\n\n\ndef find_entry_points() -\u003e List[str]:\n    \"\"\"Find entry point candidates.\"\"\"\n    found = []\n    for candidate in ENTRY_CANDIDATES:\n        if Path(candidate).exists():\n            found.append(candidate)\n    return found\n\n\ndef find_lint_config() -\u003e List[str]:\n    \"\"\"Find linting and formatting config files.\"\"\"\n    found = []\n    for filename in LINT_FILES:\n        if Path(filename).exists():\n            found.append(filename)\n    return found\n\n\ndef find_env_templates() -\u003e List[tuple]:\n    \"\"\"Find environment variable templates.\"\"\"\n    found = []\n    for filename in ENV_TEMPLATES:\n        path = Path(filename)\n        if path.exists():\n            found.append((filename, path))\n    return found\n\n\ndef search_todos() -\u003e List[str]:\n    \"\"\"Search for TODO/FIXME/HACK comments.\"\"\"\n    todos = []\n    patterns = [\"TODO\", \"FIXME\", \"HACK\"]\n    exclude_dirs_str = \"|\".join(EXCLUDE_DIRS | {\"test\", \"tests\", \"__tests__\", \"spec\", \"__mocks__\", \"fixtures\"})\n\n    try:\n        for root, dirs, files in os.walk(Path.cwd()):\n            # Remove excluded directories from dirs to prevent os.walk from descending\n            dirs[:] = [d for d in dirs if d not in EXCLUDE_DIRS and d not in {\"test\", \"tests\", \"__tests__\", \"spec\", \"__mocks__\", \"fixtures\"}]\n\n            for file in files:\n                # Check file extension\n                ext = Path(file).suffix.lstrip('.')\n                if ext not in SOURCE_EXTS:\n                    continue\n\n                filepath = Path(root) / file\n                try:\n                    with open(filepath, 'r', encoding='utf-8', errors='replace') as f:\n                        for line_num, line in enumerate(f, 1):\n                            for pattern in patterns:\n                                if pattern in line:\n                                    rel_path = filepath.relative_to(Path.cwd())\n                                    todos.append(f\"{rel_path}:{line_num}: {line.strip()}\")\n                except Exception:\n                    pass\n    except Exception:\n        pass\n\n    return todos[:TODO_LIMIT]\n\n\ndef get_git_commits() -\u003e List[str]:\n    \"\"\"Get recent git commits.\"\"\"\n    try:\n        result = subprocess.run(\n            [\"git\", \"log\", \"--oneline\", \"-n\", str(RECENT_COMMITS_LIMIT)],\n            capture_output=True,\n            text=True,\n            cwd=Path.cwd()\n        )\n        if result.returncode == 0:\n            return result.stdout.strip().split('\\n') if result.stdout.strip() else []\n        return []\n    except Exception:\n        return []\n\n\ndef get_git_churn() -\u003e List[str]:\n    \"\"\"Get high-churn files from last 90 days.\"\"\"\n    try:\n        result = subprocess.run(\n            [\"git\", \"log\", \"--since=90 days ago\", \"--name-only\", \"--pretty=format:\"],\n            capture_output=True,\n            text=True,\n            cwd=Path.cwd()\n        )\n        if result.returncode == 0:\n            files = [f.strip() for f in result.stdout.split('\\n') if f.strip()]\n            # Count occurrences\n            from collections import Counter\n            counts = Counter(files)\n            churn = sorted(counts.items(), key=lambda x: x[1], reverse=True)\n            return [f\"{count:4d} {filename}\" for filename, count in churn[:CHURN_LIMIT]]\n        return []\n    except Exception:\n        return []\n\n\ndef is_git_repo() -\u003e bool:\n    \"\"\"Check if current directory is a git repository.\"\"\"\n    try:\n        subprocess.run(\n            [\"git\", \"rev-parse\", \"--git-dir\"],\n            capture_output=True,\n            cwd=Path.cwd(),\n            timeout=2\n        )\n        return True\n    except Exception:\n        return False\n\n\ndef detect_monorepo() -\u003e List[str]:\n    \"\"\"Detect monorepo signals.\"\"\"\n    signals = []\n\n    for filename in MONOREPO_FILES:\n        if Path(filename).exists():\n            signals.append(f\"Monorepo tool detected: {filename}\")\n\n    for dirname in MONOREPO_DIRS:\n        if Path(dirname).is_dir():\n            signals.append(f\"Sub-package directory found: {dirname}/\")\n\n    # Check package.json workspaces\n    if Path(\"package.json\").exists():\n        try:\n            with open(\"package.json\", 'r') as f:\n                content = f.read()\n                if '\"workspaces\"' in content:\n                    signals.append(\"package.json has 'workspaces' field (npm/yarn workspaces monorepo)\")\n        except Exception:\n            pass\n\n    return signals\n\n\ndef detect_ci_cd_pipelines() -\u003e List[str]:\n    \"\"\"Detect CI/CD pipeline configurations.\"\"\"\n    pipelines = []\n\n    for config_path, pipeline_name in CI_CD_CONFIGS.items():\n        path = Path(config_path)\n        if path.is_file():\n            pipelines.append(f\"CI/CD: {pipeline_name}\")\n        elif path.is_dir():\n            # Check for workflow files in directory\n            try:\n                if list(path.glob(\"*.yml\")) or list(path.glob(\"*.yaml\")):\n                    pipelines.append(f\"CI/CD: {pipeline_name}\")\n            except Exception:\n                pass\n\n    return pipelines\n\n\ndef detect_containers() -\u003e List[str]:\n    \"\"\"Detect containerization and orchestration configs.\"\"\"\n    containers = []\n\n    for config in CONTAINER_FILES:\n        path = Path(config)\n        if path.is_file():\n            if \"Dockerfile\" in config:\n                containers.append(\"Container: Docker found\")\n            elif \"docker-compose\" in config:\n                containers.append(\"Orchestration: Docker Compose found\")\n            elif config.endswith(\".yaml\") or config.endswith(\".yml\"):\n                containers.append(f\"Container/Orchestration: {config}\")\n        elif path.is_dir():\n            if config in [\"k8s\", \"kubernetes\"]:\n                containers.append(\"Orchestration: Kubernetes configs found\")\n            try:\n                if list(path.glob(\"*.yml\")) or list(path.glob(\"*.yaml\")):\n                    containers.append(f\"Container/Orchestration: {config}/ directory found\")\n            except Exception:\n                pass\n\n    return containers\n\n\ndef detect_security_configs() -\u003e List[str]:\n    \"\"\"Detect security and compliance configurations.\"\"\"\n    security = []\n\n    for config in SECURITY_CONFIGS:\n        if Path(config).exists():\n            config_name = config.replace(\".yml\", \"\").replace(\".yaml\", \"\").lstrip(\".\")\n            security.append(f\"Security: {config_name}\")\n\n    return security\n\n\ndef detect_performance_markers() -\u003e List[str]:\n    \"\"\"Detect performance testing and profiling markers.\"\"\"\n    performance = []\n\n    for marker in PERFORMANCE_MARKERS:\n        if Path(marker).exists():\n            performance.append(f\"Performance: {marker} found\")\n        else:\n            # Check for directories\n            try:\n                if Path(marker).is_dir():\n                    performance.append(f\"Performance: {marker}/ directory found\")\n            except Exception:\n                pass\n\n    return performance\n\n\ndef collect_code_metrics() -\u003e dict:\n    \"\"\"Collect code metrics: file counts by extension, total LOC.\"\"\"\n    metrics = {\n        \"total_files\": 0,\n        \"by_extension\": {},\n        \"by_language\": {},\n        \"total_lines\": 0,\n        \"largest_files\": []\n    }\n\n    # Language mapping\n    lang_map = {\n        \"ts\": \"TypeScript\", \"tsx\": \"TypeScript/React\", \"js\": \"JavaScript\",\n        \"jsx\": \"JavaScript/React\", \"py\": \"Python\", \"go\": \"Go\",\n        \"java\": \"Java\", \"kt\": \"Kotlin\", \"rs\": \"Rust\",\n        \"cs\": \"C#\", \"rb\": \"Ruby\", \"php\": \"PHP\",\n        \"swift\": \"Swift\", \"scala\": \"Scala\", \"ex\": \"Elixir\",\n        \"cpp\": \"C++\", \"c\": \"C\", \"h\": \"C Header\",\n        \"clj\": \"Clojure\", \"lua\": \"Lua\", \"hs\": \"Haskell\"\n    }\n\n    file_sizes = []\n\n    try:\n        for root, dirs, files in os.walk(Path.cwd()):\n            dirs[:] = [d for d in dirs if d not in EXCLUDE_DIRS]\n\n            for file in files:\n                filepath = Path(root) / file\n                ext = filepath.suffix.lstrip('.')\n\n                if not ext or ext in {\"pyc\", \"o\", \"a\", \"so\"}:\n                    continue\n\n                try:\n                    size = filepath.stat().st_size\n                    file_sizes.append((filepath.relative_to(Path.cwd()), size))\n\n                    metrics[\"total_files\"] += 1\n                    metrics[\"by_extension\"][ext] = metrics[\"by_extension\"].get(ext, 0) + 1\n\n                    lang = lang_map.get(ext, \"Other\")\n                    metrics[\"by_language\"][lang] = metrics[\"by_language\"].get(lang, 0) + 1\n\n                    # Count lines for text files\n                    if ext in SOURCE_EXTS and size \u003c 1_000_000:  # Skip huge files\n                        try:\n                            with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:\n                                metrics[\"total_lines\"] += len(f.readlines())\n                        except Exception:\n                            pass\n                except Exception:\n                    pass\n\n        # Top 10 largest files\n        file_sizes.sort(key=lambda x: x[1], reverse=True)\n        metrics[\"largest_files\"] = [\n            f\"{str(f)}: {s/1024:.1f}KB\" for f, s in file_sizes[:10]\n        ]\n\n    except Exception:\n        pass\n\n    return metrics\n\n\ndef print_section(title: str, content: List[str], output_file=None) -\u003e None:\n    \"\"\"Print a section with title and content.\"\"\"\n    lines = [f\"\\n=== {title} ===\"]\n\n    if isinstance(content, list):\n        lines.extend(content if content else [\"None found.\"])\n    elif isinstance(content, str):\n        lines.append(content)\n\n    text = '\\n'.join(lines) + '\\n'\n\n    if output_file:\n        output_file.write(text)\n    else:\n        print(text, end='')\n\n\ndef main():\n    \"\"\"Main entry point.\"\"\"\n    args = parse_args()\n\n    output_file = None\n    if args.output:\n        output_dir = Path(args.output).parent\n        output_dir.mkdir(parents=True, exist_ok=True)\n        output_file = open(args.output, 'w', encoding='utf-8')\n        print(f\"Writing output to: {args.output}\", file=sys.stderr)\n\n    try:\n        # Directory tree\n        print_section(\n            f\"DIRECTORY TREE (max depth {TREE_MAX_DEPTH}, source files only)\",\n            get_directory_tree(),\n            output_file\n        )\n\n        # Stack detection\n        manifests = find_manifest_files()\n        if manifests:\n            manifest_content = [\"\"]\n            for manifest in manifests:\n                manifest_path = Path(manifest)\n                manifest_content.append(f\"--- {manifest} ---\")\n                if manifest == \"bun.lockb\":\n                    manifest_content.append(\"[Binary lockfile — see package.json for dependency details.]\")\n                else:\n                    manifest_content.append(read_file_preview(manifest_path))\n            print_section(\"STACK DETECTION (manifest files)\", manifest_content, output_file)\n        else:\n            print_section(\"STACK DETECTION (manifest files)\", [\"No recognized manifest files found in project root.\"], output_file)\n\n        # Entry points\n        entries = find_entry_points()\n        if entries:\n            entry_content = [f\"Found: {e}\" for e in entries]\n            print_section(\"ENTRY POINTS\", entry_content, output_file)\n        else:\n            print_section(\"ENTRY POINTS\", [\"No common entry points found. Check 'main' or 'scripts.start' in manifest files above.\"], output_file)\n\n        # Linting config\n        lint = find_lint_config()\n        if lint:\n            lint_content = [f\"Found: {l}\" for l in lint]\n            print_section(\"LINTING AND FORMATTING CONFIG\", lint_content, output_file)\n        else:\n            print_section(\"LINTING AND FORMATTING CONFIG\", [\"No linting or formatting config files found in project root.\"], output_file)\n\n        # Environment templates\n        envs = find_env_templates()\n        if envs:\n            env_content = []\n            for filename, filepath in envs:\n                env_content.append(f\"--- {filename} ---\")\n                env_content.append(read_file_preview(filepath))\n            print_section(\"ENVIRONMENT VARIABLE TEMPLATES\", env_content, output_file)\n        else:\n            print_section(\"ENVIRONMENT VARIABLE TEMPLATES\", [\"No .env.example or .env.template found. Identify required environment variables by searching the code and config for environment variable reads.\"], output_file)\n\n        # TODOs\n        todos = search_todos()\n        if todos:\n            print_section(\"TODO / FIXME / HACK (production code only, test dirs excluded)\", todos, output_file)\n        else:\n            print_section(\"TODO / FIXME / HACK (production code only, test dirs excluded)\", [\"None found.\"], output_file)\n\n        # Git info\n        if is_git_repo():\n            commits = get_git_commits()\n            if commits:\n                print_section(\"GIT RECENT COMMITS (last 20)\", commits, output_file)\n            else:\n                print_section(\"GIT RECENT COMMITS (last 20)\", [\"No commits found.\"], output_file)\n\n            churn = get_git_churn()\n            if churn:\n                print_section(\"HIGH-CHURN FILES (last 90 days, top 20)\", churn, output_file)\n            else:\n                print_section(\"HIGH-CHURN FILES (last 90 days, top 20)\", [\"None found.\"], output_file)\n        else:\n            print_section(\"GIT RECENT COMMITS (last 20)\", [\"Not a git repository or no commits yet.\"], output_file)\n            print_section(\"HIGH-CHURN FILES (last 90 days, top 20)\", [\"Not a git repository.\"], output_file)\n\n        # Monorepo detection\n        monorepo = detect_monorepo()\n        if monorepo:\n            print_section(\"MONOREPO SIGNALS\", monorepo, output_file)\n        else:\n            print_section(\"MONOREPO SIGNALS\", [\"No monorepo signals detected.\"], output_file)\n\n        # Code metrics\n        metrics = collect_code_metrics()\n        metrics_output = [\n            f\"Total files scanned: {metrics['total_files']}\",\n            f\"Total lines of code: {metrics['total_lines']}\",\n            \"\"\n        ]\n        if metrics[\"by_language\"]:\n            metrics_output.append(\"Files by language:\")\n            for lang, count in sorted(metrics[\"by_language\"].items(), key=lambda x: x[1], reverse=True):\n                metrics_output.append(f\"  {lang}: {count}\")\n        if metrics[\"largest_files\"]:\n            metrics_output.append(\"\")\n            metrics_output.append(\"Top 10 largest files:\")\n            metrics_output.extend(metrics[\"largest_files\"])\n        print_section(\"CODE METRICS\", metrics_output, output_file)\n\n        # CI/CD Detection\n        ci_cd = detect_ci_cd_pipelines()\n        if ci_cd:\n            print_section(\"CI/CD PIPELINES\", ci_cd, output_file)\n        else:\n            print_section(\"CI/CD PIPELINES\", [\"No CI/CD pipelines detected.\"], output_file)\n\n        # Container Detection\n        containers = detect_containers()\n        if containers:\n            print_section(\"CONTAINERS \u0026 ORCHESTRATION\", containers, output_file)\n        else:\n            print_section(\"CONTAINERS \u0026 ORCHESTRATION\", [\"No containerization configs detected.\"], output_file)\n\n        # Security Configs\n        security = detect_security_configs()\n        if security:\n            print_section(\"SECURITY \u0026 COMPLIANCE\", security, output_file)\n        else:\n            print_section(\"SECURITY \u0026 COMPLIANCE\", [\"No security configs detected.\"], output_file)\n\n        # Performance Markers\n        performance = detect_performance_markers()\n        if performance:\n            print_section(\"PERFORMANCE \u0026 TESTING\", performance, output_file)\n        else:\n            print_section(\"PERFORMANCE \u0026 TESTING\", [\"No performance testing configs detected.\"], output_file)\n\n        # Final message\n        final_msg = \"\\n=== SCAN COMPLETE ===\\n\"\n        if output_file:\n            output_file.write(final_msg)\n        else:\n            print(final_msg, end='')\n\n        return 0\n\n    except Exception as e:\n        print(f\"Error: {e}\", file=sys.stderr)\n        return 1\n\n    finally:\n        if output_file:\n            output_file.close()\n\n\nif __name__ == \"__main__\":\n    sys.exit(main())\n"},"import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/tree/541b7819d8c3545c6df122491af4fa1eae415779/skills/acquire-codebase-knowledge"}},"content_hash":[11,77,166,252,113,140,243,119,193,240,244,63,171,12,62,122,133,221,227,115,42,4,227,13,59,167,79,60,208,108,237,33],"trust_level":"unsigned","yanked":false}