# Spec Kit Codebase Scout

> A Claude skill from lksnext-ai-lab/spec-kit-template.

- **Type:** Skill
- **Install:** `agentstack add skill-lksnext-ai-lab-spec-kit-template-spec-kit-codebase-scout`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lksnext-ai-lab](https://agentstack.voostack.com/s/lksnext-ai-lab)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [lksnext-ai-lab](https://github.com/lksnext-ai-lab)
- **Source:** https://github.com/lksnext-ai-lab/spec-kit-template/tree/main/.github/skills/spec-kit-codebase-scout

## Install

```sh
agentstack add skill-lksnext-ai-lab-spec-kit-template-spec-kit-codebase-scout
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill: codebase_scout

## Objetivo

Explorar `codebase/**` (**solo lectura**) para construir/actualizar un **mapa técnico as-is** útil para el flujo SPEC (plan/write/review), minimizando el riesgo de inventar.

**Output principal:**
- `docs/spec/_inputs/codebase-map.md`

**Outputs secundarios (si aplica):**
- `docs/spec/95-open-questions.md` (OPENQ-### nuevas cuando falte evidencia)
- Recomendación de Evidence Pack cuando el tema requiera profundidad (`evidence_pack`).

---

## Principios

- **Read-only**: nunca modificar `codebase/**`.
- **Evidencia primero**: afirmaciones técnicas relevantes deben estar sustentadas con rutas concretas.
- **No inventar**: si no se confirma, se registra `OPENQ`.
- **Mapa operativo**: síntesis accionable, no enciclopedia.
- **Seguridad**: no copiar secretos (tokens, API keys, credenciales, `.env` reales).

---

## Entradas

- `codebase/**` (solo lectura)
- (Opcional) Pistas del usuario: rutas, módulos, términos, servicios
- (Opcional) Evidence Packs existentes: `docs/spec/_inputs/evidence/`

---

## Salidas

1) `docs/spec/_inputs/codebase-map.md` (crear/actualizar)
2) `OPENQ-###` en `docs/spec/95-open-questions.md` si hay gaps críticos
3) (Opcional) “Recomendación EP”: listar qué Evidence Packs conviene generar y por qué

---

## Timeboxing (obligatorio)

Elegir un modo (por defecto: **Quick**):

### Quick scan (15–30 min)
- Stack + tooling
- Entry point(s)
- Estructura de carpetas (alto nivel)
- 5–10 módulos/capacidades con evidencia mínima
- Persistencia (BBDD/ORM/migraciones) si se encuentra rápido
- CI/tests (mención breve)

### Deep scan (60–90 min)
Además de lo anterior:
- Interfaces públicas (punto de definición de rutas o resumen por familias)
- Jobs/workers/cron/colas (si existen)
- Logging/observabilidad/config más detallado
- 10–20 módulos/capacidades con evidencias

Si el timebox se agota:
- priorizar completar **DoD mínimo** y abrir `OPENQ` en lo crítico.

---

## Reglas duras (hard rules)

1) **Prohibido modificar codebase**
2) **Evidencia estándar**
   - Cada afirmación importante debe incluir `EVIDENCE:` con rutas `codebase/...`
   - Si no hay evidencia, no se formula como hecho → `OPENQ`.
3) **Sin secretos**
   - No copiar valores de `.env`/secrets ni tokens. A lo sumo: “existe `.env.example` / variable X”.
4) **Confianza**
   - No usar “probablemente”. O está confirmado con evidencia, o se formula como `OPENQ`.
5) **Cambios diff-friendly**
   - Actualizar por secciones sin reescrituras masivas.

---

## Procedimiento (pasos)

### 1) Stack y tooling (as-is)
Buscar evidencias en ficheros típicos:
- Node/TS: `package.json`, lockfile, `tsconfig*`
- Python: `pyproject.toml`, `requirements.txt`, `poetry.lock`
- Java: `pom.xml`, `build.gradle`
- Docker: `Dockerfile`, `docker-compose.yml`
- Mono-repo: `turbo.json`, `nx.json`, `pnpm-workspace.yaml`

Registrar:
- runtime(s), framework(s), gestor de deps
- scripts relevantes (`dev`, `build`, `test`, `lint`)

### 2) Entry point(s) y bootstrap
Localizar:
- punto de arranque
- carga de config/env
- registro de routers/modules

Registrar:
- entrypoint confirmado
- cómo se compone la app (muy alto nivel)

### 3) Estructura de carpetas (alto nivel)
Listar 8–20 carpetas max con 1 línea de propósito.
Evitar listas infinitas.

### 4) Módulos/capacidades
Definir “módulo” como:
- carpeta/paquete con responsabilidades claras (p.ej. `auth`, `users`, `repositories`)
- y normalmente al menos 2 de: router/controller, service, schema/model, policy/middleware

Para cada módulo (5–10 Quick / 10–20 Deep):
- 1–3 rutas clave
- 1 línea de qué hace

### 5) Interfaces públicas (Deep o si es fácil)
- Dónde se definen rutas (router index / controllers)
- Si hay OpenAPI/Swagger, registrarlo con evidencia

### 6) Persistencia y datos
Identificar:
- DB
- ORM
- migraciones
- nombres de entidades principales (solo nombres)

### 7) Calidad y operación
Mencionar (con evidencia):
- tests: ubicación + framework
- CI/CD: workflows/pipelines
- logging/observabilidad: librerías/config (alto nivel)
- config: `.env.example`, `config/`, settings

---

## Formato obligatorio para `codebase-map.md`

El documento debe incluir estas secciones (aunque alguna sea breve):

1) **Resumen ejecutivo** (5–10 líneas)
2) **Última actualización** (YYYY-MM-DD) + modo (Quick/Deep)
3) **Stack y tooling**
4) **Entrypoints y bootstrap**
5) **Estructura de carpetas (alto nivel)**
6) **Módulos/capacidades**
7) **Interfaces públicas** (si aplica / OPENQ)
8) **Persistencia** (si aplica / OPENQ)
9) **Operación** (tests/CI/logging/config)
10) **Evidencias** (lista)
11) **Cobertura del scout**:
    - paths inspeccionados
    - términos buscados (si aplica)
12) **OPENQ detectadas** (links)

### Estándar de evidencia
Usar bullets tipo:
- `EVIDENCE: codebase/src/main.ts` — bootstrap servidor
- `EVIDENCE: codebase/src/modules/auth/*` — módulo auth
- `EVIDENCE: codebase/.github/workflows/ci.yml` — pipeline CI

---

## Cuándo escalar a Evidence Pack (recomendación)

Si se detecta que requiere investigación específica y es crítico para decisiones:
- auth/roles/permisos
- secretos/API keys
- arquitectura async/jobs/colas
- integraciones externas críticas
- modelo de datos sensible

Entonces:
- recomendar `EP-###` y describir qué preguntas debe responder.

---

## DoD (mínimo para considerarlo “suficiente”)

- [ ] Stack + tooling (o OPENQ)
- [ ] Entry point(s) (o OPENQ)
- [ ] Estructura de carpetas (alto nivel)
- [ ] 5–10 módulos (Quick) o 10–20 (Deep) con evidencia
- [ ] Persistencia (o OPENQ)
- [ ] CI/tests/logging/config mencionados (o OPENQ)
- [ ] Sección “Evidencias” y “Cobertura del scout”
- [ ] OPENQ registradas si hay gaps críticos

---

## Anti-patrones

- “Probablemente usan X” sin evidencia
- Listas de archivos sin síntesis
- Mezclar to-be (SPEC) dentro del as-is (CODEBASE)
- Copiar secretos o valores de `.env`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lksnext-ai-lab](https://github.com/lksnext-ai-lab)
- **Source:** [lksnext-ai-lab/spec-kit-template](https://github.com/lksnext-ai-lab/spec-kit-template)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-lksnext-ai-lab-spec-kit-template-spec-kit-codebase-scout
- Seller: https://agentstack.voostack.com/s/lksnext-ai-lab
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.