Adds a new Agent Skill - Acquire-Codebase-Knowledge (#1373)

* feat(skill): add acquire-codebase-knowledge skill documentation

* feat(templates): add architecture, concerns, conventions, integrations, stack, structure, and testing documentation templates

* feat(references): add inquiry checkpoints and stack detection documentation

* feat(scan): add script to collect project discovery information for acquire-codebase-knowledge skill

* feat(skills): add acquire-codebase-knowledge skill for codebase mapping and documentation

* feat(scan): enhance scan script with absolute path handling and improved output variable validation

* feat(scan): replace bash script with Python script for project discovery information collection

* feat(skills): update acquire-codebase-knowledge skill to replace scan.sh with scan.py

skills/acquire-codebase-knowledge/assets/templates/ARCHITECTURE.md

@@ -0,0 +1,49 @@
+# Architecture
+
+## Core Sections (Required)
+
+### 1) Architectural Style
+
+- Primary style: [layered/feature/event-driven/other]
+- Why this classification: [short evidence-backed rationale]
+- Primary constraints: [2-3 constraints that shape design]
+
+### 2) System Flow
+
+```text
+[entry] -> [processing] -> [domain logic] -> [data/integration] -> [response/output]
+```
+
+Describe the flow in 4-6 steps using file-backed evidence.
+
+### 3) Layer/Module Responsibilities
+
+| Layer or module | Owns | Must not own | Evidence |
+|-----------------|------|--------------|----------|
+| [name] | [responsibility] | [non-responsibility] | [file] |
+
+### 4) Reused Patterns
+
+| Pattern | Where found | Why it exists |
+|---------|-------------|---------------|
+| [singleton/repository/adapter/etc] | [path] | [reason] |
+
+### 5) Known Architectural Risks
+
+- [Risk 1 + impact]
+- [Risk 2 + impact]
+
+### 6) Evidence
+
+- [path/to/entrypoint]
+- [path/to/main-layer-files]
+- [path/to/data-or-integration-layer]
+
+## Extended Sections (Optional)
+
+Add only when needed:
+
+- Startup or initialization order details
+- Async/event topology diagrams
+- Anti-pattern catalog with refactoring paths
+- Failure-mode analysis and resilience posture

skills/acquire-codebase-knowledge/assets/templates/CONCERNS.md

@@ -0,0 +1,56 @@
+# Codebase Concerns
+
+## Core Sections (Required)
+
+### 1) Top Risks (Prioritized)
+
+| Severity | Concern | Evidence | Impact | Suggested action |
+|----------|---------|----------|--------|------------------|
+| [high/med/low] | [issue] | [file or scan output] | [impact] | [next action] |
+
+### 2) Technical Debt
+
+List the most important debt items only.
+
+| Debt item | Why it exists | Where | Risk if ignored | Suggested fix |
+|-----------|---------------|-------|-----------------|---------------|
+| [item] | [reason] | [path] | [risk] | [fix] |
+
+### 3) Security Concerns
+
+| Risk | OWASP category (if applicable) | Evidence | Current mitigation | Gap |
+|------|--------------------------------|----------|--------------------|-----|
+| [risk] | [A01/A03/etc or N/A] | [path] | [what exists] | [what is missing] |
+
+### 4) Performance and Scaling Concerns
+
+| Concern | Evidence | Current symptom | Scaling risk | Suggested improvement |
+|---------|----------|-----------------|-------------|-----------------------|
+| [issue] | [path/metric] | [symptom] | [risk] | [action] |
+
+### 5) Fragile/High-Churn Areas
+
+| Area | Why fragile | Churn signal | Safe change strategy |
+|------|-------------|-------------|----------------------|
+| [path] | [reason] | [recent churn evidence] | [approach] |
+
+### 6) `[ASK USER]` Questions
+
+Add unresolved intent-dependent questions as a numbered list.
+
+1. [ASK USER] [question]
+
+### 7) Evidence
+
+- [scan output section reference]
+- [path/to/code-file]
+- [path/to/config-or-history-evidence]
+
+## Extended Sections (Optional)
+
+Add only when needed:
+
+- Full bug inventory
+- Component-level remediation roadmap
+- Cost/effort estimates by concern
+- Dependency-risk and ownership mapping

skills/acquire-codebase-knowledge/assets/templates/CONVENTIONS.md

@@ -0,0 +1,52 @@
+# Coding Conventions
+
+## Core Sections (Required)
+
+### 1) Naming Rules
+
+| Item | Rule | Example | Evidence |
+|------|------|---------|----------|
+| Files | [RULE] | [EXAMPLE] | [FILE] |
+| Functions/methods | [RULE] | [EXAMPLE] | [FILE] |
+| Types/interfaces | [RULE] | [EXAMPLE] | [FILE] |
+| Constants/env vars | [RULE] | [EXAMPLE] | [FILE] |
+
+### 2) Formatting and Linting
+
+- Formatter: [TOOL + CONFIG FILE]
+- Linter: [TOOL + CONFIG FILE]
+- Most relevant enforced rules: [RULE_1], [RULE_2], [RULE_3]
+- Run commands: [COMMANDS]
+
+### 3) Import and Module Conventions
+
+- Import grouping/order: [RULE]
+- Alias vs relative import policy: [RULE]
+- Public exports/barrel policy: [RULE]
+
+### 4) Error and Logging Conventions
+
+- Error strategy by layer: [SHORT SUMMARY]
+- Logging style and required context fields: [SUMMARY]
+- Sensitive-data redaction rules: [SUMMARY]
+
+### 5) Testing Conventions
+
+- Test file naming/location rule: [RULE]
+- Mocking strategy norm: [RULE]
+- Coverage expectation: [RULE or TODO]
+
+### 6) Evidence
+
+- [path/to/lint-config]
+- [path/to/format-config]
+- [path/to/representative-source-file]
+
+## Extended Sections (Optional)
+
+Add only for large or inconsistent codebases:
+
+- Layer-specific error handling matrix
+- Language-specific strictness options
+- Repo-specific commit/branching conventions
+- Known convention violations to clean up

skills/acquire-codebase-knowledge/assets/templates/INTEGRATIONS.md

@@ -0,0 +1,48 @@
+# External Integrations
+
+## Core Sections (Required)
+
+### 1) Integration Inventory
+
+| System | Type (API/DB/Queue/etc) | Purpose | Auth model | Criticality | Evidence |
+|--------|---------------------------|---------|------------|-------------|----------|
+| [name] | [type] | [purpose] | [auth] | [high/med/low] | [file] |
+
+### 2) Data Stores
+
+| Store | Role | Access layer | Key risk | Evidence |
+|-------|------|--------------|----------|----------|
+| [db/cache/etc] | [role] | [module] | [risk] | [file] |
+
+### 3) Secrets and Credentials Handling
+
+- Credential sources: [env/secrets manager/config]
+- Hardcoding checks: [result]
+- Rotation or lifecycle notes: [known/unknown]
+
+### 4) Reliability and Failure Behavior
+
+- Retry/backoff behavior: [implemented/none/partial]
+- Timeout policy: [where configured]
+- Circuit-breaker or fallback behavior: [if any]
+
+### 5) Observability for Integrations
+
+- Logging around external calls: [yes/no + where]
+- Metrics/tracing coverage: [yes/no + where]
+- Missing visibility gaps: [list]
+
+### 6) Evidence
+
+- [path/to/integration-wrapper]
+- [path/to/config-or-env-template]
+- [path/to/monitoring-or-logging-config]
+
+## Extended Sections (Optional)
+
+Add only when needed:
+
+- Endpoint-by-endpoint catalog
+- Auth flow sequence diagrams
+- SLA/SLO per integration
+- Region/failover topology notes

skills/acquire-codebase-knowledge/assets/templates/STACK.md

@@ -0,0 +1,56 @@
+# Technology Stack
+
+## Core Sections (Required)
+
+### 1) Runtime Summary
+
+| Area | Value | Evidence |
+|------|-------|----------|
+| Primary language | [VALUE] | [FILE_PATH] |
+| Runtime + version | [VALUE] | [FILE_PATH] |
+| Package manager | [VALUE] | [FILE_PATH] |
+| Module/build system | [VALUE] | [FILE_PATH] |
+
+### 2) Production Frameworks and Dependencies
+
+List only high-impact production dependencies (frameworks, data, transport, auth).
+
+| Dependency | Version | Role in system | Evidence |
+|------------|---------|----------------|----------|
+| [NAME] | [VERSION] | [ROLE] | [FILE_PATH] |
+
+### 3) Development Toolchain
+
+| Tool | Purpose | Evidence |
+|------|---------|----------|
+| [TOOL] | [LINT/FORMAT/TEST/BUILD] | [FILE_PATH] |
+
+### 4) Key Commands
+
+```bash
+[install command]
+[build command]
+[test command]
+[lint command]
+```
+
+### 5) Environment and Config
+
+- Config sources: [LIST FILES]
+- Required env vars: [VAR_1], [VAR_2], [TODO]
+- Deployment/runtime constraints: [SHORT NOTE]
+
+### 6) Evidence
+
+- [path/to/manifest]
+- [path/to/runtime-config]
+- [path/to/build-or-ci-config]
+
+## Extended Sections (Optional)
+
+Add only when needed for complex repos:
+
+- Full dependency taxonomy by category
+- Detailed compiler/runtime flags
+- Environment matrix (dev/stage/prod)
+- Process manager and container runtime details

skills/acquire-codebase-knowledge/assets/templates/STRUCTURE.md

@@ -0,0 +1,44 @@
+# Codebase Structure
+
+## Core Sections (Required)
+
+### 1) Top-Level Map
+
+List only meaningful top-level directories and files.
+
+| Path | Purpose | Evidence |
+|------|---------|----------|
+| [path/] | [purpose] | [source] |
+
+### 2) Entry Points
+
+- Main runtime entry: [FILE]
+- Secondary entry points (worker/cli/jobs): [FILES or NONE]
+- How entry is selected (script/config): [NOTE]
+
+### 3) Module Boundaries
+
+| Boundary | What belongs here | What must not be here |
+|----------|-------------------|------------------------|
+| [module/layer] | [responsibility] | [forbidden logic] |
+
+### 4) Naming and Organization Rules
+
+- File naming pattern: [kebab/camel/Pascal + examples]
+- Directory organization pattern: [feature/layer/domain]
+- Import aliasing or path conventions: [RULE]
+
+### 5) Evidence
+
+- [path/to/root-tree-source]
+- [path/to/entry-config]
+- [path/to/key-module]
+
+## Extended Sections (Optional)
+
+Add only when repository complexity requires it:
+
+- Subdirectory deep maps by feature/layer
+- Middleware/boot order details
+- Generated-vs-source layout boundaries
+- Monorepo workspace-level structure maps

skills/acquire-codebase-knowledge/assets/templates/TESTING.md

@@ -0,0 +1,57 @@
+# Testing Patterns
+
+## Core Sections (Required)
+
+### 1) Test Stack and Commands
+
+- Primary test framework: [NAME + VERSION]
+- Assertion/mocking tools: [TOOLS]
+- Commands:
+
+```bash
+[run all tests]
+[run unit tests]
+[run integration/e2e tests]
+[run coverage]
+```
+
+### 2) Test Layout
+
+- Test file placement pattern: [co-located/tests folder/etc]
+- Naming convention: [pattern]
+- Setup files and where they run: [paths]
+
+### 3) Test Scope Matrix
+
+| Scope | Covered? | Typical target | Notes |
+|-------|----------|----------------|-------|
+| Unit | [yes/no] | [modules/services] | [notes] |
+| Integration | [yes/no] | [API/data boundaries] | [notes] |
+| E2E | [yes/no] | [user flows] | [notes] |
+
+### 4) Mocking and Isolation Strategy
+
+- Main mocking approach: [module/class/network]
+- Isolation guarantees: [what is reset and when]
+- Common failure mode in tests: [short note]
+
+### 5) Coverage and Quality Signals
+
+- Coverage tool + threshold: [value or TODO]
+- Current reported coverage: [value or TODO]
+- Known gaps/flaky areas: [list]
+
+### 6) Evidence
+
+- [path/to/test-config]
+- [path/to/representative-test-file]
+- [path/to/ci-or-coverage-config]
+
+## Extended Sections (Optional)
+
+Add only when needed:
+
+- Framework-specific suite patterns
+- Detailed mock recipes per dependency type
+- Historical flaky test catalog
+- Test performance bottlenecks and optimization ideas