start

Files (1)

• SKILL.md

SKILL.md (first lines)

# Using Specture (Entry Point & Router)

<EXTREMELY-IMPORTANT>
If you are operating under Specture, you cannot skip this skill. Your job here is NOT to do work — it is to detect what state the project is in and route to the correct phase. Do not write code, do not run setup, do not start brainstorming until you have completed the routing logic below.
</EXTREMELY-IMPORTANT>

## Mental Model

Specture is a **state machine**. The state of the user's project is determined by which files exist on disk, not by chat history. Always trust the filesystem over conversation memory.

## Routing Algorithm

Run these checks **in order**. Stop at the first match and invoke the indicated skill.

> **Cost rule (mandatory):** routing is a filesystem state machine, not a comprehension task. **Never read full file contents for routing.** Use existence checks for Steps 1-3; read only the single `frontend.framework` field for Step 4; read only the epic checkbox lines for Step 5. For Step 2's docs-index fallback, grep for `tags:.*requirements` lines only — do NOT load the full index. Opening `stack.yml`, `business_requirements.md`, or `docs-index.yml` in full here is wasted context.

### Step 0 — Schema drift (one script call, read-only)

Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.js" check --brief` (Antigravity: `${PLUGIN_ROOT}`; manual `@import` setups: `$SPECTURE_ROOT`). It prints one line and loads no document into your context. Skip it only when `.specture/stack.yml` does not exist (Step 1 will route to `setup`).

- **Pending migrations** → announce in Spanish **before** routing: *"Hay N migraciones pendientes (M mecánicas, K asistidas, C de contenido). ¿Corro `/specture:doctor migrate` antes de enrutar?"* Do **not** block: if the user declines or does not answer, continue to Step 1 — the warning stays in the transcript.
- **ERROR findings** (stale seal, duplicate ADR, broken paths) → one line naming them; they do not change the routing.
- **`config pendiente`** in the line (v2.9.0 — e.g. `quality-commands-undefined → /specture:setup (reconfigure) → quality.commands`) → one line in Spanish **before** routing, naming the command: *"`quality.commands` sin definir en `stack.yml` — el build corre sin red-check de comandos, sin LINT_REPORT y sin tests acotados; corré `/specture:setup` (reconfigure) o completalos a mano (`docs/quality-catalog.md`)"*. Do not block, and do not fold it into the WARNING count — a real project ran a whole batch without ever hearing it.
- **No Node ≥ 22** → one line, *"doctor no disponible (requiere Node ≥ 22)"*, then Step 1. Never re-implement the checks by hand.
- Nothing pending and no ERROR → say nothing; go to Step 1.

### Step 1 — Setup detection

Check whether `.specture/stack.yml` exists in the user's project root.

- **No** → invoke `./skills/setup/SKILL.md`. Stop.
- **Yes** → continue to Step 2.

### Step 2 — Discovery detection

Check whether `docs/01-requirements/business_requirements.md` exists.

- **Yes** → continue to Step 3.
- **No** → check the fallback path: does `.specture/docs-index.yml` exist AND does it contain at least one entry with the tag `requirements`? (Grep for lines matching `tags:.*requirements` — single pass, no full parse.)

  - **Index exists with requirements entries** → the team already has requirements documented in a preexisting docs folder; do NOT route to `discover` (that would re-extract knowledge that already exists). Ask the user:

    > "Detecté que el proyecto tiene documentación preexistente indexada (`.specture/docs-index.yml`) con `<N>` entradas categorizadas como `requirements`, pero no existe el archivo puente `docs/01-requirements/business_requirements.md`. Opciones:
    >
    > (a) Generar el puente automáticamente desde el índice (recomendado — invoca `setup-docs-bridge`).
    > (b) Ir a `discover` para levantar requerimientos desde cero (descartando lo indexado).
    > (c) Continuar sin bridge (no recomendado — algunas skills no encontrarán el archivo)."

    Route based on the user's answer:
    - `(a)` → invoke `./skills/setup-docs-bridge/SKILL.md` (bridge-only refresh: skip Phase 1 detection — the user has already accepted; resume from Phase 2 with the index's `source_of_truth_dir` as input). Stop.
    - `(b)` → invoke `./skills/discover/SKILL.md`. Stop.
    - `(c)` → continue to Step 3, but warn that downstream skills may fail their input checks.

  - **No index OR index has no requirements entries** → invoke `./skills/discover/SKILL.md`. Stop. (Original behavior preserved.)

### Step 3 — Architecture & Plan detection

Check whether `docs/04-roadmap/ROADMAP.md` exists.

- **No** → invoke `./skills/architecture/SKILL.md`. Stop.
- **Yes** → continue to Step 4.

### Step 4 — UX detection (only if frontend exists)

Read **only the `frontend.framework` field** of `.specture/stack.yml` (not the whole file). If it is set and not `none`/`null`:

Check whether **both** `docs/03-ux-ui/navigation_map.md` **and** `docs/03-ux-ui/design_system.md` exist (both are universal deliverables).

- **Either missing** → invoke `./skills/ux-design/SKILL.md`. Stop.
- **Both present (or no frontend)** → continue to Step 5.

### Step 5 — Iterative Build detection

Read **only the epic checkbox lines** of `docs/04-roadmap/ROADMAP.md` (grep the `[ ]`/`[/]`/`[x]` markers — do not load the whole document).

| State | Action |
|-------|--------|
| Any epic marked `[ ]` (pending) or `[/]` (in progress) | Invoke `./skills/build/SKILL.md` — since v2.3.0 it opens (or resumes, if `review.js status` says `OPEN`) the batch review first: one sitting of decisions, then execution without questions |
| All epics marked `[x]` (complete) | Ask the user: "El ROADMAP está 100% completo. ¿Quieres (a) auditar el código completo, (b) agregar una nueva funcionalidad, o (c) finalizar?" — and, when `hooks/lib/compliance.js status` answers `PENDING`, add "(d) decidir los hallazgos de cumplimiento pendientes" (→ `compliance-review` `triage`). Then route to the chosen path. |

## Transversal Skills

These are NOT routed by state — they are activated by symptoms during any phase:

| Symptom | Invoke |
|---------|--------|
| Test fails 2+ times in a row, or implementer is stuck guessing (except a build's `BLOCKED: supersesiones` — already classified, it runs the supersession loop — and never from inside an epic-agent, which reports `BLOCKED: debug`) | `./skills/debug/SKILL.md` |
| User wants to add a feature not in the original ROADMAP | `./skills/new-feature/SKILL.md` |
| About to claim "done", "complete", "passing", "fixed" | `./skills/verify/SKILL.md` |
| User wants to create or modify a Specture skill | `./skills/write-skill/SKILL.md` |
| Frontend & backend are out of sync (wrong URLs, shapes the backend doesn't return) in an existing project | `./skills/contract-sync-audit/SKILL.md` |
| User wants to capture session learnings, or audit the docs-index (opt-in / periodic) | `./skills/knowledge/SKILL.md` — modes `capture` / `audit` (aliases `/specture:learn`, `/specture:audit-knowledge`) |
| User wants a milestone's code checked against ALL the project rules ("revisión de cumplimiento"), or a compliance report waits for triage (`hooks/lib/compliance.js status` → `PENDING`) | `./skills/compliance-review/SKILL.md` — modes `milestone <N>` / `triage` |
| User wants a pull request (GitHub, Azure DevOps) or a branch reviewed against the project rules ("revisá el PR 123", "revisá mi rama contra develop") — never posts | `./skills/compliance-review/SKILL.md` — modes `pr <número\|url>` / `rama <rama>` |

## Red Flags — STOP

If you find yourself thinking any of the following, you are violating Specture discipline:

| Thought | Reality |
|---------|---------|
| "Es un cambio pequeño, lo codifico directo" | Every code change must be backed by a `.spec.md`. |
| "Asumo esta regla de negocio para avanzar" | Forbidden. Ask the user. |
| "Voy a leer todo el repo para tener contexto" | Token waste. Read only the active spec and the files it references. |
| "El test falló, voy a cambiar el test para que pase" | Iron Law: zero fixes without root cause. Invoke `debug/SKILL.md`. |
| "Sé qué fase tocaría aunque no haya verificado los archivos" | Trust the filesystem, not your memory. Run the routing algorithm. |

## After You Route

Announce to the user (in Spanish, since the user-facing language is Spanish):

> "Detecté que el proyecto está en la fase **[NOMBRE]**. Voy a usar el skill `[ARCHIVO]` para continuar."

Then invoke that skill and follow its instructions. Do not perform additional analysis or commentary before invoking.

**Exception — running AS the `specture-router` subagent**: do not invoke the skill. Emit the router's strict output (`PHASE: <name> · SKILL: <path>`) and stop; the main chat invokes the skill. A subagent that executes phases burns tokens outside the user's view and can't ask the user anything.

From FerEscobarDev/Specture, MIT.

More from FerEscobarDev/Specture