@ancleto/spec 0.1.0

package/skills/ancleto-commit/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: ancleto-commit
+description: Create semantic git commit following conventional commits (conventional commits, protected branches, semantic messages)
+license: MIT
+compatibility: Requires git
+metadata:
+  author: ancleto
+  version: '1.0'
+  category: git-workflow
+---
+
+Create a semantic git commit following semantic commit standards.
+
+**When to use**: User wants to commit changes with proper semantic commit message.
+
+**Steps**
+
+1. **Check current branch and status**
+
+   ```bash
+   git rev-parse --abbrev-ref HEAD
+   git status
+   ```
+
+   If on a protected branch (main, master, develop, qa, sandbox):
+
+   - ⚠️ Warn the user
+   - Suggest creating a feature branch: `feat/`, `fix/`, `chore/`
+   - Ask if they want to proceed anyway or create a branch first
+
+2. **Determine commit scope**
+
+   Ask the user (using AskUserQuestion):
+
+   - "What files should be included in this commit?"
+     - Option 1: "Only staged files (git commit)" (Recommended if files are staged)
+     - Option 2: "Stage and commit all changes (git add . && git commit)"
+     - Option 3: "Let me stage files manually first"
+
+   If option 3: Stop and let user stage files, then re-run this skill.
+
+3. **Analyze changes**
+
+   ```bash
+   git diff --staged  # if only staged
+   # or
+   git diff          # if staging all
+   ```
+
+4. **Generate semantic commit message(s)**
+
+   Based on the diff, propose 1-2 commit messages following conventional commits:
+
+   **Format:**
+
+   ```
+   type(scope): short description in present tense
+
+   Detailed explanation of WHY this change is needed.
+   Optional: Additional context, breaking changes, etc.
+
+   ```
+
+   **Types:**
+
+   - `feat`: New feature
+   - `fix`: Bug fix
+   - `chore`: Maintenance (dependencies, configs, etc.)
+   - `docs`: Documentation only
+   - `refactor`: Code restructuring (no behavior change)
+   - `test`: Adding/updating tests
+   - `perf`: Performance improvement
+
+   **Scope:** Optional, e.g., `(api)`, `(ui)`, `(auth)`
+
+   **Examples:**
+
+   ```
+   feat(auth): add JWT token refresh mechanism
+
+   Implements automatic token refresh before expiration to improve
+   user experience and reduce re-authentication requests.
+
+   ```
+
+5. **Show command before executing**
+
+   Display the exact git command that will be executed:
+
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   type(scope): description
+
+   Detailed explanation
+
+   EOF
+   )"
+   ```
+
+   Use heredoc format to ensure proper multi-line formatting.
+
+6. **Execute commit**
+
+   After user confirmation, execute the command.
+   Then run `git status` to verify success.
+
+**Guardrails**
+
+- ❌ NEVER modify git config
+- ❌ NEVER force push or use destructive commands
+- ❌ NEVER skip hooks (--no-verify) unless explicitly requested
+- ❌ NEVER commit sensitive files (.env, credentials, tokens)
+- ⚠️ Warn before committing to protected branches
+- ✅ Always use heredoc for multi-line commit messages
+
+**Related Documentation**
+
+- See `git-commits.md` for full commit conventions

package/skills/ancleto-pr/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: ancleto-pr
+description: Create pull request in Azure DevOps following conventional commits (semantic title, detailed description, test plan)
+license: MIT
+compatibility: Requires Azure DevOps CLI (az repos)
+metadata:
+  author: ancleto
+  version: '1.0'
+  category: git-workflow
+---
+
+Create a pull request in Azure DevOps following semantic standards.
+
+**When to use**: User wants to create a PR for their current branch.
+
+**Steps**
+
+1. **Validate branch state**
+
+   ```bash
+   git rev-parse --abbrev-ref HEAD
+   git status
+   ```
+
+   **Checks:**
+
+   - ❌ If on protected branch (main, master, develop, qa, sandbox): Error and stop
+   - ⚠️ If uncommitted changes: Warn and suggest committing first
+   - ✅ If clean: Proceed
+
+2. **Check remote tracking**
+
+   ```bash
+   git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null
+   ```
+
+   If no upstream tracking:
+
+   - Suggest: `git push -u origin <branch-name>`
+   - Ask if they want to push now or do it manually
+
+3. **Determine base branch**
+
+   Ask the user (using AskUserQuestion):
+
+   - "What branch should this PR merge into?"
+     - Option 1: "main" (Recommended for most features)
+     - Option 2: "develop" (if using gitflow)
+     - Option 3: "Other (specify)"
+
+4. **Analyze all changes in the PR**
+
+   ```bash
+   git log <base-branch>..HEAD --oneline
+   git diff <base-branch>...HEAD --stat
+   ```
+
+   Review ALL commits that will be included, not just the latest one.
+
+5. **Generate PR title and description**
+
+   **Title format:** `type: Short description (<70 chars)`
+
+   - Use the same types as commits: feat, fix, chore, docs, etc.
+   - Keep concise, details go in description
+
+   **Description format:**
+
+   ```markdown
+   ## Summary
+
+   - Bullet point 1 of main changes
+   - Bullet point 2 of main changes
+   - Bullet point 3 of main changes
+
+   ## Technical Details
+
+   - Key implementation decisions
+   - Architecture changes (if any)
+   - Dependencies added/updated (if any)
+
+   ## Test Plan
+
+   - [ ] Unit tests pass (`npm test`)
+   - [ ] Integration tests pass (if applicable)
+   - [ ] Manual testing performed
+   - [ ] Tested on [environment/browser/device]
+   - [ ] Edge cases covered
+
+   ## Breaking Changes
+
+   _None_ OR _List breaking changes and migration steps_
+
+   ## Related Issues
+
+   - Closes #123 (if applicable)
+   - Related to #456 (if applicable)
+
+   ---
+
+   🤖 Generated with [OpenCode](https://opencode.ai)
+   ```
+
+6. **Show PR command before executing**
+
+   Display the exact `az repos pr create` command:
+
+   ```bash
+   az repos pr create \
+     --title "feat: add user authentication" \
+     --description "$(cat <<'EOF'
+   ## Summary
+   ...
+
+   🤖 Generated with OpenCode
+   EOF
+   )" \
+     --source-branch <current-branch> \
+     --target-branch <base-branch>
+   ```
+
+   Use heredoc for description to ensure proper formatting.
+
+7. **Create PR**
+
+   After user confirmation, execute the command.
+
+   **On success:**
+
+   - Show the PR URL
+   - Suggest next steps: request reviewers, link work items, etc.
+
+   **On error:**
+
+   - If "az not found": Install Azure CLI and authenticate
+   - If "not authenticated": Run `az login`
+   - If other errors: Show error and suggest manual PR creation
+
+**Guardrails**
+
+- ❌ NEVER create PR from protected branches
+- ❌ NEVER force push before creating PR
+- ⚠️ Warn if uncommitted changes exist
+- ✅ Always analyze ALL commits in the branch, not just the latest
+- ✅ Include test plan checklist
+- ✅ Use heredoc for multi-line description
+- ✅ Add "Generated with OpenCode" footer
+
+**Alternative: GitHub PRs**
+
+If using GitHub instead of Azure DevOps, use `gh pr create`:
+
+```bash
+gh pr create \
+  --title "feat: add user authentication" \
+  --body "$(cat <<'EOF'
+...
+EOF
+)"
+```
+
+**Related Documentation**
+
+- See `CONTRIBUTING.md` for the PR review process

package/skills/ancleto-technical-discovery/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ancleto-technical-discovery
+description: >
+  Use for ANY question about a repository whose answer spans more than one file: what the
+  repo is and how it works, architecture, domains, end-to-end flows, business rules and
+  where they live, impact of a change, onboarding. Answers from the technical seed in
+  docs/technical-discovery/ instead of sweeping the repo, and generates or updates that
+  seed when it is missing, partial, or stale. ALWAYS use it — never sweep the repo by hand
+  — including vague requests such as "explicame este repo", "explicame cómo funciona este
+  repo", "de qué trata este proyecto", "cómo está armado este repo", "explicame la
+  arquitectura", "explorá/analizá el repositorio", "dame un overview del proyecto", or
+  "onboarding", and their English equivalents. Skip it only when a single known symbol,
+  file, or line directly answers the question.
+license: MIT
+metadata:
+  author: ancleto
+  version: '2.3'
+  category: discovery
+---
+
+# ancleto-technical-discovery
+
+The technical seed is a compact, navigable map rather than a repository inventory. It
+preserves the facts that prevent repeated exploration: architecture, entry points,
+business rules, integrations, risks, and coupling. **Every document generated by this
+skill must be written in Spanish**, including headings, tables, descriptions, findings,
+and frontmatter values intended for readers.
+
+The CLI packages the repository and computes state; this skill decides which information
+belongs in the seed. When invoked by `@technical-seed-writer`, do not delegate generation
+further or create one subagent per unit: generation happens in one sequential execution.
+
+## When to use it
+
+- Default: any question that needs repository context, however vaguely phrased, starts
+  here. Run `ancleto discovery --check` first and follow this flow.
+- Only exception: when one symbol, file, or line directly answers the question, read the
+  code directly.
+
+| State | Action |
+| --- | --- |
+| `READY` | Read `index.md` and at most two documents it routes to. |
+| `PARTIAL` | Complete only the missing documents. |
+| `STALE` | Regenerate only the affected focused dossier; update a transversal decision when it changed. |
+| `MISSING` | Generate the concise seed. |
+
+Never replace a missing seed with a manual repository sweep.
+
+## Concise generation
+
+Read `references/generation-pipeline.md` and `references/output-contract.md`. In short:
+
+1. Use the single global pack specified in the pipeline. Its output is the complete context
+   for this generation; never run a preliminary pack, a second compressed pack.
+2. Write all required root documents and `units/_map.md` from that pack before answering
+   the repository question.
+3. Select at most **three** dossiers only when the same global pack contains enough evidence
+   to explain a high-impact flow, rule, integration, or risk. Represent all other units in
+   `units/_map.md` with their purpose and entry point.
+4. Close with `inventory.md` using directories or globs, never one row per file.
+
+Do not create empty documents merely to fill a fixed list. Record absent or unproven
+evidence briefly in `unknowns.md`. Do not include secrets: name the variable or file and
+always omit the value.
+
+## Reading
+
+1. Read `index.md`.
+2. Select a single reading path.
+3. Open only that destination and, if needed, one linked dossier.
+4. Answer in Spanish and cite the paths referenced by the seed.
+
+The seed provides orientation. To confirm a specific or recently changed detail, read only
+the cited source file.

package/skills/ancleto-technical-discovery/references/archetypes/api-layered.md

@@ -0,0 +1,8 @@
+# Archetype: layered API
+
+Signals: controllers, services, repositories, and dependency registration.
+
+Prioritize dossiers for resources with write operations, complex authorization, or rules
+distributed across layers. In the Spanish unit map, link each resource to representative
+routes and controller, service, and persistence paths. Record HTTP contracts and unauthenticated
+routes in Spanish in `decisions.md`.

package/skills/ancleto-technical-discovery/references/archetypes/monorepo.md

@@ -0,0 +1,8 @@
+# Archetype: monorepo
+
+Signals: workspaces, `nx.json`, `turbo.json`, `pnpm-workspace.yaml`, or several manifests.
+
+`units/_map.md` must summarize every workspace in Spanish with its purpose, entry point,
+and direct dependencies. Choose dossiers only for up to three workspaces that connect
+products, expose a shared API, or concentrate a critical rule. Root configuration belongs
+in `setup.md`.

package/skills/ancleto-technical-discovery/references/archetypes/ops-tooling.md

@@ -0,0 +1,7 @@
+# Archetype: operational tooling
+
+Signals: manual commands, scripts, filesystem outputs, and environment selection.
+
+Prioritize dossiers for operations that write outside the repository or reach production.
+In Spanish, `decisions.md` must describe the destination, reversibility, and required
+confirmations without repeating the full implementation.

package/skills/ancleto-technical-discovery/references/archetypes/service-legacy.md

@@ -0,0 +1,7 @@
+# Archetype: hybrid legacy service
+
+Signals: server views, JavaScript served as static assets, and configuration-borne rules.
+
+Prioritize rules that cross server, DOM, and client, especially when two implementations
+exist. Describe divergence in Spanish in `decisions.md`; create a dossier only when the
+complete flow is useful for future changes.

package/skills/ancleto-technical-discovery/references/archetypes/spa.md

@@ -0,0 +1,7 @@
+# Archetype: SPA
+
+Signals: a client router, bundler, components, and shared state.
+
+The Spanish map must identify routes, state, HTTP client, and design system. Prioritize a
+dossier for a flow connecting an API response to a rendered value, or for a highly coupled
+boundary. Avoid a dossier per screen or component.

package/skills/ancleto-technical-discovery/references/discovery-config.md

@@ -0,0 +1,24 @@
+# Discovery configuration (`.ancletorc`)
+
+`.ancletorc` is a JSON file at the repository root. `ancleto init` owns its installation fields
+(`version`, `installedAt`, `profile`, `tool`, and `installedPaths`) and preserves the team's
+`discovery` section when the tooling is reinstalled. The technical-discovery skill must never
+rewrite any part of this file.
+
+The optional `discovery` object configures the technical seed:
+
+| Key | Meaning | Default |
+| --- | --- | --- |
+| `outputDir` | Relative directory for generated seed documents. | `docs/technical-discovery` |
+| `archetype` | `auto`, `monorepo`, `api-layered`, `spa`, `ops-tooling`, or `service-legacy`. | `auto` |
+| `readBudgetTokens` | Reading budget for a focused dossier. | `6000` |
+| `exclude` | Extra glob patterns omitted from packs, coverage, and source hashes. | CLI defaults |
+
+`node_modules` and `.git` are always excluded, even when the team supplies its own list.
+When `exclude` is configured, it supplements those structural exclusions; it does not replace
+them.
+
+Never read `.ancletorc` directly during generation. Run `ancleto discovery --check` and use the
+returned `config`, which has already validated the file, applied defaults, and reported any
+unknown configuration keys. Pass its resolved exclusions to the one Repomix command as
+described by `generation-pipeline.md`.

package/skills/ancleto-technical-discovery/references/generation-pipeline.md

@@ -0,0 +1,56 @@
+# Concise generation pipeline
+
+Generation prioritizes signal over literal coverage. It runs in one sequential execution
+with no subagents and exactly **one** Repomix pack. The result contains eight base documents
+and up to three focused dossiers. All generated documents must be written in Spanish.
+
+## 1. Global map
+
+First run `ancleto discovery --check` and read its JSON. Its `config` is the resolved
+`discovery` section of `.ancletorc`, including defaults, so it is the only configuration source
+for this execution. Use `config.outputDir` as the only output location and copy the resolved
+`config.exclude` globs into the pack command. Do not parse, create, or edit `.ancletorc` yourself.
+Then run exactly once:
+
+```bash
+ancleto discovery --compress --ignore "<config.exclude joined by commas>"
+```
+
+`--check` and the final validation do not create packs. Do **not** run an uncompressed pack
+first, do not run `--compress` a second time, and do not run `--include`: the single global
+pack is sufficient context for every document in this seed. The CLI also merges
+`discovery.exclude`; passing the resolved list makes the exclusion scope explicit and must
+not be replaced with an empty `--ignore` flag.
+
+Read the pack path printed by that one command. From its contents, identify the archetype,
+entry points, main boundaries, and candidate units, then immediately write these Spanish
+documents under `config.outputDir`:
+
+- `index.md`: question router.
+- `overview.md`: purpose, architecture, components, and main journeys.
+- `setup.md`: commands, environments, variable names, and operational conventions.
+- `decisions.md`: rules, contracts, risks, debt, or coupling that affect technical choices.
+- `integrations.md`: external systems and observable private dependencies.
+- `units/_map.md`: a compact table of relevant units, their purpose, entry point, and dossier when present.
+- `unknowns.md`: evidence limits.
+- `inventory.md`: covered directories or globs.
+
+## 2. Focused dossiers
+
+Select zero to three units in this order: critical business flow, component boundary,
+external integration, configuration-borne rule, or change risk. Create
+`units/<unit>.md` from the **same global pack** with the dossier template; do not run another
+command to refine its context. If the global pack does not establish enough evidence, omit
+the dossier and record the evidence limit in `unknowns.md`.
+
+A dossier is not a transcript: it describes responsibilities, flow, rules, and key paths.
+When it exceeds `readBudgetTokens`, keep only facts that answer cross-cutting questions;
+do not split it or create child documents.
+
+## 3. Close and update
+
+Run `ancleto discovery --check` once more and apply `validation-checklist.md`. This is a
+state-only validation; it must not be followed by another Repomix command. For stale nodes,
+regenerate only the affected documents using one new global generation on a later request.
+If a unit has no dossier, update its row in `units/_map.md` and only the root documents whose
+content changed.

package/skills/ancleto-technical-discovery/references/node-frontmatter.md

@@ -0,0 +1,30 @@
+# Seed frontmatter
+
+Every generated document declares its purpose and provenance in YAML. Reader-facing values,
+including `read_when`, must be written in Spanish.
+
+| Field | Required | Purpose |
+| --- | --- | --- |
+| `node` | yes | Relative identifier within the seed. |
+| `kind` | yes | `router`, `overview`, `setup`, `decisions`, `integrations`, `inventory`, `unknowns`, or `dossier`. |
+| `read_when` | yes | Question class answered by the document, in Spanish. |
+| `sources` | dossiers only | Globs for relevant sources. |
+| `sourcesSha` | dossiers only | CLI-computed hash for those globs. |
+| `generatedAt` | yes | Generation timestamp. |
+| `pluginVersion` | yes | Plugin version reported by the CLI. |
+| `skillVersion` | yes | This skill version. |
+
+The generated dossier frontmatter must follow this Spanish example:
+
+```yaml
+---
+node: units/pagos
+kind: dossier
+read_when: preguntas sobre el cobro y sus reglas
+sources: ["apps/api/pagos/**", "libs/pagos/**"]
+sourcesSha: <hash>
+generatedAt: <ISO timestamp>
+pluginVersion: <version>
+skillVersion: '2.3'
+---
+```

package/skills/ancleto-technical-discovery/references/output-contract.md

@@ -0,0 +1,36 @@
+# Output contract
+
+The seed is concise, verifiable, and entirely written in Spanish. It does not cover every
+file; it covers the decisions and paths an agent should not need to reconstruct from
+scratch.
+
+## Configuration, provenance, and legacy layouts
+
+`.ancletorc` is the repository-level configuration and installation record maintained by
+`ancleto init`. Its optional `discovery` section configures the seed's `outputDir`,
+`archetype`, `readBudgetTokens`, and extra `exclude` globs. The skill consumes the resolved
+copy returned by `ancleto discovery --check`; it never edits `.ancletorc` and does not treat it as
+seed content or evidence.
+
+## Include
+
+- Architecture, entry points, and component boundaries.
+- Business rules in configuration or duplicated across locations.
+- Integrations, observable contracts, and private dependencies.
+- Risks, coupling, and the impact of changing a component.
+- Key paths that allow each claim to be checked.
+
+Classify claims as `declarado`, `observado`, `inferido` (with confidence), `conflictivo`,
+or `desconocido`. Do not invent facts; put evidence limits in `unknowns.md`.
+
+## Size limits
+
+- Root documents are dense and brief; do not repeat the same fact in several documents.
+- Generate at most three focused dossiers.
+- A dossier cites only files that explain its behaviour. It has no per-file or per-directory inventory.
+- `inventory.md` uses globs or directories as orientation, not as an audit.
+
+## Secrets
+
+Never copy credential values. Name the variable, key, or file and state that its value was
+omitted. Record the relevant risk in `decisions.md`.

package/skills/ancleto-technical-discovery/references/templates/dossier.md

@@ -0,0 +1,38 @@
+# Focused dossier template
+
+Use only for one of up to three high-impact units. Instructions are in English, but the
+generated document must use the following Spanish structure and Spanish prose.
+
+```markdown
+---
+node: units/<unidad>
+kind: dossier
+read_when: preguntas sobre <flujo, regla o integración>
+covers: [<temas>]
+sources: ["<globs>"]
+sourcesSha: <hash from CLI>
+generatedAt: <ISO timestamp>
+pluginVersion: <version from report>
+skillVersion: '2.3'
+---
+
+# <Unidad>
+
+## Propósito
+
+<Qué resuelve y por qué importa.>
+
+## Recorrido relevante
+
+<Entrada → transformación → salida, con paths clave.>
+
+## Reglas, contratos y riesgos
+
+<Solo los hallazgos que afectan decisiones o cambios.>
+
+## Paths clave
+
+| Path | Rol |
+| --- | --- |
+| `<path>` | <rol verificable> |
+```

package/skills/ancleto-technical-discovery/references/templates/inventory.md

@@ -0,0 +1,22 @@
+# Scope inventory template
+
+`inventory.md` provides coverage orientation, not a file list. Instructions are in English;
+the generated document and its table values must be in Spanish.
+
+```markdown
+---
+node: inventory
+kind: inventory
+read_when: verificar el alcance documentado de la semilla
+generatedAt: <ISO timestamp>
+pluginVersion: <version from report>
+skillVersion: '2.3'
+---
+
+# Alcance documentado
+
+| Alcance | Documento | Motivo |
+| --- | --- | --- |
+| `apps/**` | `overview.md` | Entrypoints y composición principal |
+| `libs/pagos/**` | `units/pagos.md` | Flujo comercial crítico |
+```

package/skills/ancleto-technical-discovery/references/templates/setup.md

@@ -0,0 +1,27 @@
+# Setup template
+
+`setup.md` records only the operational information needed to run, test, and orient within
+the repository. The generated document must use Spanish and never copy secret values.
+
+```markdown
+---
+node: setup
+kind: setup
+read_when: preparar el entorno o ejecutar los comandos principales
+generatedAt: <ISO timestamp>
+pluginVersion: <version from report>
+skillVersion: '2.3'
+---
+
+# Setup
+
+## Comandos principales
+
+| Objetivo | Comando | Fuente |
+| --- | --- | --- |
+| <objetivo> | `<comando>` | `<path>` |
+
+## Entornos y variables
+
+<Nombre de variable, propósito y path de referencia; nunca su valor.>
+```

package/skills/ancleto-technical-discovery/references/validation-checklist.md

@@ -0,0 +1,12 @@
+# Validation checklist
+
+- [ ] Every generated document is in Spanish.
+- [ ] Required root documents exist and `ancleto discovery --check` reports `READY`.
+- [ ] The resolved `config` from `ancleto discovery --check` was used; `.ancletorc` was not edited.
+- [ ] There are at most three dossiers under `units/` (excluding `_map.md`).
+- [ ] `index.md` lets a reader choose a destination without reading sibling documents.
+- [ ] Each relevant claim cites a path and states its evidence when it is not direct.
+- [ ] `decisions.md` concentrates rules, risks, and coupling without duplicating the overview.
+- [ ] `inventory.md` declares directories or globs, not file lists.
+- [ ] `unknowns.md` records what could not be verified.
+- [ ] No secret values are present.