EJECUTAR AHORA
Objetivo: $ARGUMENTS
Todos los documentos en la KB viven en una colección: un directorio bajo kb/ con un COLLECTION.md local, como kb/notes/, kb/reference/, kb/instructions/, o una colección de biblioteca instalada como kb/commonplace/notes/. Cada colección que acepta escrituras tiene un COLLECTION.md con su registro, objetivo de calidad, ofertas de tipo y convenciones de enlace.
Los documentos con frontmatter llevan un type: valorado como ruta que apunta a un documento de especificación de tipo, por ejemplo type: kb/types/note.md o type: kb/reference/types/adr.md. Los archivos sin frontmatter son implícitamente text.
Paso 1 - Analizar argumentos
Modo edición: el primer argumento es una ruta a un archivo .md existente. Léelo, infiere la colección de la ruta y lee su ruta type: del frontmatter. Si tiene frontmatter pero no type:, detente y arregla ese problema estructural antes de editar. Si no tiene frontmatter, trátalo como text implícito. Abre el documento de especificación de tipo nombrado por type: antes de hacer cambios estructurales.
Modo nueva escritura: todo lo demás. Extrae colección, tipo y tema de los argumentos. Valores por defecto: colección notes, tipo kb/types/note.md. Si el tipo solicitado es una instrucción y no hay colección explícita, usa la colección instructions.
Para nuevas escrituras, resuelve la colección objetivo a un directorio bajo kb/ con un COLLECTION.md local; los nombres abreviados como notes significan kb/notes/. Lee la sección ## Types de esa colección y elige una ruta de tipo listada. Si el tipo solicitado no está listado y el usuario no dio una ruta explícita, detente y lista los tipos disponibles. Si el usuario da una ruta de tipo explícita kb/.../*.md, abre ese archivo y verifica que sea un documento de especificación de tipo antes de usarlo.
Paso 2 - Cargar convenciones de la colección
Lee el COLLECTION.md de la colección objetivo para las convenciones de escritura, incluyendo las reglas de enlace saliente. Encuentra la sección de enlace saliente (el encabezado varía — busca el que nombra destinos y etiquetas) y trátala como autoritativa. Te dice a qué colecciones de destino puede enlazar esta fuente, qué destinos están excluidos, qué etiquetas están autorizadas para cada par fuente->destino y la necesidad del lector que satisface cada etiqueta. El formato interno varía (bloques por destino, una tabla única de etiquetas con una columna de destinos, prosa) — léelo por contenido, no por forma. No hay un documento de enlace separado para consultar.
Fallo duro si la colección objetivo no tiene COLLECTION.md. Cada colección que acepta escrituras debe tener un COLLECTION.md; su registro, objetivo de calidad y reglas de enlace son lo que distingue a las colecciones. No procedas con convenciones por defecto.
Paso 3 - Cargar la especificación de tipo
Lee el documento de especificación de tipo seleccionado. Su frontmatter debe incluir type: kb/types/type-spec.md, name, description y schema. Su cuerpo proporciona la forma del artefacto y puede incluir un bloque de plantilla. Sigue ese cuerpo como el contrato estructural de autoría.
No recurras a note desde una ruta de tipo faltante.
Para text, escribe markdown sin procesar sin frontmatter solo cuando el usuario quiera explícitamente captura no estructurada. De lo contrario, usa kb/types/note.md.
Paso 4 - Buscar antes de escribir
Escribir no ejecuta descubrimiento activo — ese es trabajo de cp-skill-connect. Escribir redacta una nota y confirma solo los enlaces que el autor ya tiene a mano, más una guardia barata contra duplicados:
- Verificación de casi duplicados. Busca en la colección objetivo los términos distintivos del título de la nueva nota con
rg(ej.rg -i "término clave" kb/notes/ --glob "*.md"). Esta es una búsqueda de términos específica — no enumeres toda la colección; un listado completo cuesta contexto lineal y es la herramienta incorrecta para la verificación de duplicados de una sola nota. Si ya existe un casi duplicado, prefiere editarlo en lugar de crear una segunda nota. - Contexto ya cargado. Las notas, fuentes e ingestiones traídas a la sesión para esta escritura son candidatos de enlace de primera clase. Si valió la pena leerlo, vale la pena considerarlo como enlace.
- Objetivos nombrados por el usuario. Objetivos de enlace que el usuario menciona en el prompt.
En modo edición, también ejecuta una consulta de backlinks en la nota objetivo — una consulta, sin búsqueda en el cuerpo — para que las ediciones no dejen dependientes huérfanos.
Todo descubrimiento más allá de esto — escaneos de descripción en toda la colección, prospección entre destinos, búsqueda en el cuerpo, recorrido de etiquetas, seguimiento de enlaces, razonamiento de arista inversa — pertenece a cp-skill-connect, no aquí. Escribir se mantiene enfocado en redactar una nota.
Paso 5 - Redactar y guardar
Sigue el documento de especificación de tipo y las convenciones de la colección. Deriva un nombre de archivo en minúsculas con guiones de # Title a menos que estés editando un archivo existente. Para artefactos tipados, establece type: en la ruta exacta de la especificación de tipo relativa al repositorio, no en el nombre del tipo.
Establece rasgos solo cuando estén claramente justificados. Los rasgos disponibles y sus significados están definidos en la especificación del tipo objetivo (ej. la tabla de rasgos en kb/types/note.md) — toma el vocabulario de ahí, no de una lista recordada.
Preserva el frontmatter y los enlaces existentes durante las ediciones a menos que el cambio solicitado requiera cambiarlos.
Paso 6 - Validar
Valida la nota que escribiste o editaste:
commonplace-validate ruta/al/archivo.md
Arregla los fallos estructurales antes de detenerte.
Luego sugiere cp-skill-connect como el siguiente paso. El paso 4 confirma solo los enlaces que el autor ya tenía a mano (contexto cargado, nombrados por el usuario) más una guardia contra duplicados; el resto de la parte del grafo de la nota — escaneos de descripción en toda la colección, candidatos entre destinos, coincidencias de búsqueda en el cuerpo, recorrido de etiquetas, seguimiento de enlaces, candidatos de arista inversa — solo surge bajo el skill de conexión. La sugerencia no es un pulido opcional.
Mecánica universal
Estas se aplican a todos los artefactos tipados independientemente de la colección.
Frontmatter hace que las notas sean consultables. Sin frontmatter significa text implícito; cualquier archivo con frontmatter debe incluir un type: valorado como ruta. La mayoría de las notas de biblioteca también necesitan description (entre comillas dobles, 50-200 caracteres), más traits, tags y status opcionales.
Descripciones son filtros de recuperación, no resúmenes. La prueba: si un agente buscara el concepto de esta nota y obtuviera 5 resultados, ¿ayudaría esta descripción a elegir esta? Parafrasear el título no añade valor de recuperación.
Vocabulario. Usa el vocabulario activo declarado en la raíz AGENTS.md. Al escribir o editar prosa sustancialmente, glosa y enlaza el vocabulario activo en la primera mención significativa cuando el lector pueda no conocer el término. No remuevas pasajes no tocados solo para añadir enlaces de vocabulario.
Enlaces. Usa rutas markdown relativas desde el archivo fuente. Cada enlace debe apuntar a un archivo real.
La posición codifica compromiso. Los conectores en línea en prosa (desde [X](./x.md), porque [X](./x.md), pero [X](./x.md)) son los más fuertes — el objetivo es una premisa del argumento actual. Los enlaces en pie de página llevan una etiqueta explícita y una frase de contexto: - [título](./ruta.md) — etiqueta: frase de contexto.
El COLLECTION.md de la colección autoriza etiquetas por destino y nombra la necesidad del lector que satisface cada etiqueta. Elige una etiqueta cuya necesidad del lector coincida con el propósito del enlace; escribe la frase de contexto para responder "[fuente] se conecta con [destino] porque [razón específica]." Si ninguna etiqueta autorizada encaja, el candidato está fuera del alcance de esta colección — descarta el enlace o eleva el problema al autor de la colección para que extienda la autorización.
Nombres de archivo son en minúsculas, con guiones, .md, derivados de # Title, máximo 70 caracteres.
Seguimiento de destilación: al destilar desde notas a un artefacto enfocado, añade Destilado en: en el pie de página de cada nota fuente. El artefacto destilado no enlaza de vuelta.
Renombres: nunca renombres manualmente. Usa commonplace-relocate-note para actualizar los backlinks.