@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/connect-tool/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: connect-tool
+description: "Use when the user names a specific tool to connect to the agent (an ERP, accounting or desktop program, CRM, WhatsApp, a spreadsheet, a database): research its real docs, choose the safest route, build `01-TOOLS/<TOOL>/` with a test that proves it, and guide the user. NOT a full typed API client (that is `api-connector-builder`), NOT a whole-workspace tooling scan (that is `harness`)."
+tags: [connect, integration, erp, legacy, desktop, database, read-only, mcp, api, export, least-privilege, onboarding]
+recommends: [harness, api-connector-builder, automation-strategy, automation-flows]
+profiles: [minimal, core, full]
+origin: ai-hub
+---
+
+# Connect a tool: research it, pick the safe route, prove it works
+
+The user said *"connect my Holded"*, *"can the agent read our Sage?"*, *"hook up WhatsApp"*. This
+skill turns that sentence into a working, documented connection in `01-TOOLS/<TOOL>/`, for **any**
+tool: the ones with a modern API, and the program installed on an office PC fifteen years ago.
+
+ai-hub ships no ready-made connections. Every project builds only the ones its user asks for, so the
+method matters more than any list of vendors: **find the truth, take the least dangerous route,
+prove it, leave it written down.**
+
+## Before anything: what does the user want to do?
+
+Ask only what the docs cannot answer, in plain words (`technical_level` in
+`02-DOCS/wiki/harness/user-profile.md` sets the register):
+
+- **Which product, exactly?** Name, edition, version. "Sage" is five different products.
+- **Where does it run?** In the cloud (a website they log into) or installed on a computer or
+  server in the office.
+- **Read or write?** Reports and questions need reading. Entering invoices needs writing, and
+  writing is a separate, explicit decision (below).
+
+## 1. Research: the docs decide, never memory
+
+Look it up every time, even for a tool you "know": plans, endpoints and MCP servers change monthly.
+In this order, stopping when the route is clear:
+
+1. **The vendor's own developer docs**: search `<product> API`, `<product> developers`,
+   `<product> MCP`. Prefer the vendor domain over blog posts.
+2. **The official MCP registry** (`registry.modelcontextprotocol.io`) and the vendor's docs for an
+   official MCP server. An official, read-only MCP is often the fastest safe route.
+3. **Library docs** through Context7 when the route is an SDK.
+4. **Export and import features** in the product's user manual: scheduled CSV/Excel exports, FTP
+   drops, official import file formats.
+5. **Where the data lives** for installed software: the vendor's installation guide, the database
+   engine it installs (often SQL Server Express, sometimes Access, Firebird or MySQL).
+
+Write every source into the tool's `README.md` with its URL and the date you read it. **If you find
+nothing reliable, say so** and stop at a question for the vendor; an invented endpoint costs the
+user a week.
+
+## 2. Choose the route: the least dangerous one that does the job
+
+| Route | Use when | Watch for |
+|---|---|---|
+| Official MCP server | The vendor publishes one | Start it read-only if it offers the mode |
+| Official API | Documented REST/GraphQL with scoped tokens | Request read scopes only; full client work goes to `api-connector-builder` |
+| Built-in integration (OAuth app, Zapier/Make/n8n connector) | No API for you, but a supported integration exists | The integration's permissions, not yours, are the ceiling |
+| Scheduled export | The program can export CSV/Excel or drop files to a folder | Freshness is the export schedule, say so |
+| Read-only copy of the database | Installed software with no API and no export | See *Desktop programs* below; never the live database |
+| Screen automation (RPA) | Nothing else exists | Last resort: fragile and breaks on every update |
+
+**Connect, or migrate?** If every route above is poor and the program is near end-of-life, or new
+legal requirements (Spanish e-invoicing, Veri\*factu) will force a change anyway, say so plainly
+and hand the decision to `automation-strategy`. Check the current dates at the tax authority's
+site: they have moved before.
+
+## 3. Least privilege, always
+
+- **Read first.** Every connection starts read-only, even when the goal is writing.
+- **Writing is explicit.** Only when the user asks for it, only through the vendor's API or its
+  official import format, and only for the objects named.
+- **Never write directly into a desktop program's database.** It bypasses the program's own
+  rules, voids support contracts, and can corrupt accounting. Generate the program's official
+  import file instead, and a person imports it.
+- **Secrets stay in `.env`** (gitignored, `chmod 600`). Never in the repo, never in `02-DOCS`.
+
+## 4. Build it in `01-TOOLS/<TOOL>/`
+
+Copy `01-TOOLS/_TEMPLATE/` to `01-TOOLS/<TOOL>/` (uppercase id, e.g. `HOLDED`, `SAGE_50`) and fill
+every file: `.env.example` with the real variable names, `CREDENTIALS.md` with where each one is
+generated and how to rotate it, `README.md` with the route, the sources and their dates, and the
+permissions granted. Add a row to `01-TOOLS/README.md`.
+
+**`test_connection` is the proof, not a formality.** It makes one cheap read and prints
+`OK — …`. When the connection is meant to be read-only, it must also **prove that writing fails**,
+because a read-only promise nobody tested is not one:
+
+```bash
+# PostgreSQL: a write must fail with a PERMISSION error. Any other error (wrong host, bad password)
+# proves nothing, so it fails the test too instead of passing as "refused".
+out=$(psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -c "BEGIN; CREATE TABLE probe_write(i int); ROLLBACK;" 2>&1) \
+  && { echo "FAIL — this user can write" >&2; exit 1; }
+grep -qiE "permission denied|read-only transaction" <<<"$out" \
+  && echo "OK — writes refused" || { echo "FAIL — unexpected error: $out" >&2; exit 1; }
+```
+
+```bash
+# SQL Server: insert into one of the views you exposed; only error 229 (permission denied) passes.
+out=$(sqlcmd -S "$MSSQL_HOST" -U "$MSSQL_USER" -P "$MSSQL_PASSWORD" -d "$MSSQL_DB" -b \
+  -Q "BEGIN TRAN; INSERT INTO probe_views.customers DEFAULT VALUES; ROLLBACK;" 2>&1) \
+  && { echo "FAIL — this user can write" >&2; exit 1; }
+grep -q "Msg 229" <<<"$out" && echo "OK — writes refused" || { echo "FAIL — unexpected error: $out" >&2; exit 1; }
+```
+
+For an API, prove it through the token itself: list its scopes from the vendor's token endpoint
+or dashboard and fail when a write scope is present. Never fire a real write to "see what happens".
+
+## Desktop programs and old ERPs
+
+Most small-business software was never meant to be connected. The safe pattern:
+
+1. **Find the data.** The vendor's install guide, the Windows ODBC data sources, or the SQL Server
+   instance the program installed (often `.\SQLEXPRESS`). Access files are `.mdb`/`.accdb`.
+2. **Work on a copy, never the live database.** A nightly copy, off business hours. SQL Server
+   Express has no Agent: schedule `sqlcmd` with a `BACKUP DATABASE` from the Windows Task
+   Scheduler and restore it where the agent reads. Access: copy the file, then convert or read it
+   with `mdbtools` (`mdb-tables`, `mdb-export`).
+3. **A dedicated reader.** A login that can only `SELECT`, ideally only on a schema of views that
+   expose what is needed:
+
+   ```sql
+   CREATE LOGIN ia_reader WITH PASSWORD = '<from .env>';
+   CREATE USER ia_reader FOR LOGIN ia_reader;
+   GRANT SELECT ON SCHEMA::probe_views TO ia_reader;
+   ALTER ROLE db_denydatawriter ADD MEMBER ia_reader;
+   ```
+
+4. **Reach it privately.** Same network, or a private mesh (the `TAILSCALE` tool). Never open the
+   database port to the internet.
+5. **Check the support terms.** Many vendors restrict direct database access. If they do, use
+   their export or their API instead.
+
+## 5. Guide the user, in their words
+
+Say what you found, which route you chose and why, and what happens next, in short sentences.
+
+## 6. Leave it written down
+
+Record the connection in `02-DOCS` following the `harness` wiki protocol: what is connected, the
+route, the permissions, who owns the credentials, and the date. The next session, or a colleague,
+reads it instead of starting over.
+
+## Anti-patterns
+
+| If you are about to… | Do instead |
+|---|---|
+| Write the endpoint from memory | Read the vendor docs now and cite them with a date |
+| Connect with an admin account "to get started" | Create the read-only user first; it costs ten minutes |
+| Write into the program's database because it is quicker | Generate its official import file |
+| Point the agent at the live database | Read a nightly copy |
+| Call the connection done because it authenticates | Run the test; for read-only, watch the write fail |
+| Promise the vendor has an API or MCP | Say what you found, with links, or that you found nothing |
+| Build the whole typed client here | Hand it to `api-connector-builder` once the route is chosen |
+
+## See also
+
+- `../harness/SKILL.md`: owns `01-TOOLS/` and `02-DOCS/` as a whole.
+- `../api-connector-builder/SKILL.md`: auth, pagination and retries once an API is the route.
+- `../automation-strategy/SKILL.md`: whether to connect, migrate or automate at all.
+- `../automation-flows/SKILL.md`: chaining the connected tool into a workflow.
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/shared/connect-tool/evals/cases.yaml

@@ -0,0 +1,58 @@
+skill: connect-tool
+
+# Cases for connect-tool: the user names ONE tool to connect to the agent. The skill researches the
+# vendor's real docs, picks the least dangerous route (MCP, API, integration, export, read-only copy
+# of the database, RPA last), builds docs/tools/<TOOL>/ with a test that proves it (and proves writes
+# fail when read-only), guides the user and records it in docs/. It is NOT the typed API client
+# (api-connector-builder), NOT the whole-workspace scan (harness), NOT whether to automate a process
+# (automation-strategy), NOT chaining services (automation-flows).
+
+should_trigger:
+  - prompt: "Quiero que el agente lea las facturas de Holded para hacerme un resumen de cobros cada lunes."
+    why: "A named cloud tool and a read goal. The route (official API with read scopes, or an MCP if the vendor has one) must come from Holded's current docs, then a docs/tools/HOLDED/ folder with a read test."
+
+  - prompt: "Tenemos Sage 50 instalado en el ordenador de la oficina. ¿Puede el agente leer los clientes?"
+    why: "Desktop software with no public API: the legacy pattern, find where the data lives, read a nightly copy with a SELECT-only login, never the live database, and ask the distributor first."
+
+  - prompt: "Hook up our WhatsApp Business number so the agent can see incoming orders."
+    why: "A named tool where the route is not obvious (the Business app versus the Cloud API). Research decides, and reading orders is the first, read-only step."
+
+  - prompt: "Mi TPV no tiene API. ¿Cómo hago que el agente vea las ventas?"
+    why: "Non-obvious trigger: no API is not the end. The route comes from the product's export features or a read-only copy of its database, found in the vendor's docs."
+
+  - prompt: "Connect the agent to our Access database, the one the old stock program uses."
+    why: "A legacy file database. Copy the .mdb/.accdb, read it with mdbtools or convert it, and never write into the program's file."
+
+  - prompt: "¿Se puede conectar InstalWin? No sé ni por dónde empezar."
+    why: "An obscure vertical program nobody has catalogued: the method (search vendor docs, export features, the database it installs) works for it, and if nothing reliable exists the skill says so."
+
+should_not_trigger:
+  - prompt: "Write a TypeScript client for the Holded API with pagination, retries and token refresh."
+    route_to: "api-connector-builder"
+    why: "The route is already decided; what remains is building a robust typed client, which is that skill's job."
+
+  - prompt: "Set up docs/tools and docs/ for this whole repo and detect every provider we use."
+    route_to: "harness"
+    why: "A whole-workspace scan and layout, not one named tool."
+
+  - prompt: "¿Merece la pena automatizar la conciliación bancaria o la seguimos haciendo a mano?"
+    route_to: "automation-strategy"
+    why: "Whether to automate a process at all; no tool is being connected yet."
+
+  - prompt: "When a Stripe payment lands, create the invoice in Holded and post it to Slack."
+    route_to: "automation-flows"
+    why: "Chaining already-connected services into a workflow, not establishing one connection."
+
+  - prompt: "We need to receive Stripe webhooks and verify their signatures."
+    route_to: "webhooks"
+    why: "Inbound callbacks into our own service, not connecting the agent to an outside tool."
+
+capability:
+  - scenario: "A non-technical user says: 'Usamos A3 en un servidor de la oficina, lo lleva una gestoría. Quiero que el agente me diga qué clientes deben dinero.' Show what the agent does from the first answer to the end."
+    must_include:
+      - "Asks only what the docs cannot answer (edition, where it runs, who administers it) and confirms the goal is reading, not writing"
+      - "Researches the vendor's current documentation and cites sources with dates, or says plainly that nothing reliable was found"
+      - "Chooses a read-only route and never proposes writing into the program's database; if writing comes up, it goes through the official import format"
+      - "Proposes reading a nightly copy with a SELECT-only user, reached privately, never the live database exposed to the internet"
+      - "Builds docs/tools/<TOOL>/ from the template with a test_connection that proves reading works AND that a write is refused, telling a permission error apart from any other failure"
+      - "Explains the chosen route in plain words and records the connection in docs/"

package/skills/shared/constitution/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: constitution
+description: "Use when setting or amending a project's non-negotiables — stack canon, quality bars, conventions, security/a11y floors — as numbered, testable rules later phases obey. First ai-hub Spec-Kit phase; writes 02-DOCS/wiki/sdd/constitution.md. NOT a feature spec (that is `specify`), NOT the technical plan (that is `plan`), NOT the wiki itself (that is `harness`)."
+tags: [sdd, constitution, principles]
+recommends: [specify]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# constitution — the project's non-negotiable principles
+
+*The first ai-hub Spec-Kit phase. Run once per project, then amend. It writes down the rules every later phase obeys: stack canon, quality bars, conventions. Everything downstream — specify, plan, analyze, implement, verify, review — reads this file as guardrails.*
+
+A constitution is small, durable, and enforceable. It is **not** a wiki of everything you know about the project (that is what `02-DOCS/wiki/` already is, run by the `harness`). It is the short list of principles that, if violated, mean the work is wrong regardless of whether it runs. If a rule here cannot be checked or pointed at later, it does not belong here — move it to the stack wiki and link it.
+
+Not this phase: *what to build* → `../specify/SKILL.md`; the technical approach for one feature → `../plan/SKILL.md`; setting up `01-TOOLS/` + `02-DOCS/` or capturing general project knowledge → `harness`; concrete stack mechanics (*how* to configure Ruff, pytest, Tailwind tokens) → the relevant stack skill (`../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`, `../design/SKILL.md`, `../secure-coding/SKILL.md`). The constitution *names* the bar; the stack skill *enforces* it.
+
+## Model tier — `heavy` (opt-in routing)
+
+This phase's default model tier is **`heavy`** — it sets the project's non-negotiables, the highest-leverage decisions in the repo. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch in one line when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
+## Honor the register first
+
+Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` and use its `technical_level`: technical terms, or plain words with analogies. No profile yet → use analogies and ask once "technical or with analogies?", or point the user at `init`; never assume fluency. The interview is the same for every reader:
+
+- Infer almost everything from the codebase and stack wiki. Ask only the few questions that genuinely change a principle.
+- Give one line of *why* per principle proposed, and the trade-off where a rule constrains the team — in the `orient` voice.
+- For a `non-technical` reader, say in one sentence what a constitution is (the house rules every later step obeys) before drafting.
+
+## Reconcile before you write (do not duplicate the stack wiki)
+
+The harness may already hold real conventions under `02-DOCS/wiki/stack/*` (e.g. `nextjs.md`, `fastapi.md`, `postgresdb.md`). The constitution does not copy them — it **ratifies the principle and links the detail**. Run this reconciliation pass first:
+
+1. **Read the Knowledge map** — the full index lives in `02-DOCS/wiki/index.md` (root `CLAUDE.md` keeps only a short pointer to it). List every `02-DOCS/wiki/stack/*` article that exists.
+2. **Read each stack article.** Pull out anything already phrased as a rule (a version pin, a lint config, a test threshold, a naming convention).
+3. **For each existing rule, decide:** is it a *project-wide non-negotiable* (→ ratify it as a principle, linking the stack article for detail) or a *local mechanic* (→ leave it in the stack wiki, do not lift it into the constitution)?
+4. **Contradictions are findings, not fixes.** If two stack articles disagree, or a stack article contradicts what the user states now, surface it and let the user resolve — never silently pick a winner.
+
+The rule of thumb: the constitution says *"every endpoint is typed and tested to ≥80% line coverage — see `wiki/stack/fastapi.md` for the pytest setup"*. It does not paste the pytest config.
+
+## What a principle must have
+
+Every principle in the constitution is one numbered, testable statement. A vague aspiration is not a principle.
+
+- **Imperative and specific.** "Code is formatted with the repo's formatter on every commit" — not "we value clean code".
+- **Checkable.** There must be a way for `../analyze/SKILL.md` and `verify` to tell whether it held. Prefer a number, a command, or a named artifact.
+- **Owned.** If enforcement lives in a stack skill or a script, link it.
+- **Falsifiable in review.** A reviewer can point at a diff and say "this violates principle 4".
+
+```text
+Weak   — "We care about security."
+Strong — "4. No secret is ever committed; secrets load from 01-TOOLS/<provider>/.env
+          (gitignored). Enforced by secure-coding + a pre-commit secret scan."
+```
+
+## The interview (requirements-first, batched)
+
+Gather what you cannot infer, then draft. Ask in one short batch — only the questions that matter. Cover these dimensions — skip any the stack wiki already answers, and confirm rather than re-ask:
+
+1. **Stack canon** — languages, frameworks, runtime/versions, package manager. What is fixed vs. open?
+2. **Quality bar** — formatter/linter (must pass clean?), type checking (strict?), test discipline (TDD? coverage floor? what kind of tests gate a merge?).
+3. **Conventions** — naming, directory structure, module boundaries, API/error shapes, commit message format.
+4. **Branching & shipping** — branch naming, PR required?, who/what gates a merge, release cadence. (Authorship rule is fixed — see below.)
+5. **Security & privacy floor** — secret handling, authn/z baseline, data residency, dependency policy.
+6. **Accessibility & UX floor** (if there's a UI) — the minimum bar (e.g. WCAG AA, keyboard-navigable).
+7. **Performance budgets** (where they matter) — a named budget, not "should be fast".
+8. **Documentation & knowledge** — what must be written down (decisions log, the wiki) and when.
+
+For any significant either/or (e.g. "strict types or gradual?", "squash or merge commits?"), use the harness **"siempre 3 opciones"** shape where it applies: gather the constraint, present up to 3 honest options with a recommendation matched to the team's level, then ratify the choice and log it.
+
+## Fixed principles (always present)
+
+Two principles are inherited from the ai-hub ecosystem and appear in every constitution unless the user explicitly overrides them:
+
+- **Git authorship is the human's.** Commits and PRs are authored by the human (Daner Alejandro Salazar Colorado, or whoever owns the repo). No `Co-Authored-By` an AI, no "generated with" footer. Enforced at the `ship` phase.
+- **Decisions are logged.** Every significant decision is appended to `02-DOCS/wiki/sdd/decisions.md` (or the harness `decisions.md`) with date, options considered, and the why. The constitution itself is the highest-order decision record.
+
+## Drafting the constitution
+
+Write `02-DOCS/wiki/sdd/constitution.md` from the template in `references/constitution-template.md`. Keep it short — a readable constitution is 1-2 screens, not a manual. Structure:
+
+- **Header** — project name, version (`v1.0.0`), ratified date, last-amended date.
+- **Principles** — numbered, grouped by the dimensions above. Each is one testable statement; link the stack article or script that enforces it.
+- **The bar (Definition of Done)** — the merge checklist every feature must pass. This is what `verify` runs against.
+- **Amendment log** — append-only; every change recorded (see protocol below).
+
+Create `02-DOCS/wiki/sdd/` if it does not exist. Do not overwrite an existing constitution — amend it.
+
+**A draft is "complete me", not "amend me".** `ai-hub onboard` writes a skeleton with `status: draft` in the frontmatter: the template's headings, the facts onboarding knew (goal, kind, scope, workflow, detected stack) and no principle. Keep those facts, run the interview, fill the sections, then on ratification drop `status: draft`, set `version: v1.0.0` and log v1.0.0 in the amendment log.
+
+## Versioning & amendment protocol
+
+The constitution is versioned so `analyze` and `review` can cite "constitution v1.2.0, principle 4".
+
+- **Semantic-ish versioning.** MAJOR when a principle is removed or reversed (breaks existing work); MINOR when a principle is added or materially tightened; PATCH for wording/clarity with no behavior change.
+- **Amendments are append-only in the log.** Never silently edit a ratified principle — strike it (mark superseded) and add the new one, bump the version, and record date + why in the amendment log.
+- **Ratification.** A new or amended constitution is shown to the user and ratified explicitly before it takes effect. "Ratify" is an explicit yes on the shown draft; walk each change only if the user asks.
+- **Downstream notice.** When a principle changes mid-project, flag that existing specs/plans may now be inconsistent — `analyze` will catch the drift on the next run.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails / fix |
+|--------------|--------------------|
+| "I'll write a thorough constitution covering everything about the project." | That's the wiki, not the constitution. Keep only enforceable non-negotiables; link the rest. |
+| "This stack detail is important, I'll paste the lint config in here." | No. Ratify the principle, link `wiki/stack/*` for the mechanic. The constitution names the bar; the stack skill enforces it. |
+| "Two stack articles disagree — I'll just pick the stricter one." | Contradictions are findings. Surface them; the user resolves. |
+| "The principle is 'write good code' — everyone knows what that means." | Not checkable, not a principle. Make it testable or drop it. |
+| "I'll rewrite the existing constitution to match what they said today." | Amend, don't overwrite. Strike + add + bump version + log the why. |
+| "No profile yet, I'll assume they're technical." | Use analogies; ask once "technical or with analogies?" or send them to `init`. |
+| "I'll add a Co-Authored-By so the commit credits the assist." | No. Git authorship is the human's — it's a fixed principle, enforced at `ship`. |
+| "I'll ratify it myself since it's obvious." | The user ratifies. Show the draft, get the explicit yes, then it takes effect. |
+
+## Checklist before handing off
+
+- [ ] `02-DOCS/wiki/harness/user-profile.md` read; register matched to `technical_level` (or the register question asked).
+- [ ] Reconciliation pass done against every `02-DOCS/wiki/stack/*` article; contradictions surfaced, not auto-resolved.
+- [ ] Every principle is numbered, imperative, testable, and links its enforcer where one exists.
+- [ ] The Definition-of-Done checklist is present (what `verify` runs against).
+- [ ] Fixed principles included: human git authorship + decisions logged.
+- [ ] `02-DOCS/wiki/sdd/constitution.md` written with version + ratified date + amendment log.
+- [ ] Root `CLAUDE.md` `## Knowledge map` pointer has the read-first row for the constitution.
+- [ ] The constitution was shown to the user and explicitly ratified.
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+This skill's `02-DOCS` record is the constitution at `02-DOCS/wiki/sdd/constitution.md`. It is a **read-first** pointer entry, so its row stays in the short `## Knowledge map` pointer in the root `CLAUDE.md` (create `CLAUDE.md` if absent, additive only — never delete existing sections) — unlike other sdd artifacts, which are indexed in `02-DOCS/wiki/index.md` (the full Knowledge map that root `CLAUDE.md` points to). Add this row to the root pointer if it is not already present:
+
+```markdown
+| Project constitution (SDD non-negotiables) | `02-DOCS/wiki/sdd/constitution.md` |
+```
+
+Every later ai-hub Spec-Kit phase reads this file before it works. The harness maintains and improves the article over the life of the project; this skill is the place that ratifies and amends it.
+
+## Result envelope
+
+End with the parseable block every SDD phase shares, so the dispatcher can chain without
+interpreting prose (contract: `../sdd/SKILL.md`):
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "Constitution written with N numbered, testable rules the later phases inherit.",
+  "artifact": "02-DOCS/wiki/sdd/constitution.md",
+  "next_recommended": "specify",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["constitution"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Principles are inherited constraints, not choices to re-make.", "Every rule is testable or it is a preference."]
+  },
+  "evidence": ["constitution path exists", "rules numbered and testable", "decisions log appended"]
+}
+```
+
+## Next in the chain
+
+The constitution is the guardrail; now describe what to build. Hand off to **`../specify/SKILL.md`** — turn a fuzzy intent into a spec (what & why, no implementation), grounded in these principles. The full chain: **constitution → specify → clarify → plan → tasks → analyze → implement → verify → review → ship** (with `debug`, `worktrees`, `parallel` callable on demand). The dispatcher is `../sdd/SKILL.md`.

package/skills/shared/constitution/evals/README.md

@@ -0,0 +1,68 @@
+# Eval harness — `constitution` skill
+
+Two things are checked: that the skill **triggers** on the right prompts (and
+stays quiet on near-misses that belong to a sibling), and that it **measurably
+improves** the constitution it produces. Cases live in `cases.yaml`. There is no
+shell runner — `constitution` is a process skill judged on safety rails and
+judgment, so grading is done by an **agent harness** (a Claude Code agent with
+skills loaded) plus a human spot-check.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `constitution`.
+- `should_not_trigger` — near-misses that must route elsewhere (`route_to` names
+  a real sibling in this repo: `harness`, `init`, `fastapi`, `secure-coding`,
+  `design`).
+- `capability` — a scenario with a `must_include` rubric to grade with vs without.
+
+## Triggering eval
+
+Goal: the skill fires when it should and never on a near-miss.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing (constitution + its ai-hub Spec-Kit phase siblings once they exist, plus
+   harness, init, fastapi, nextjs, go, postgresdb, flutter, design, secure-coding,
+   deployment, marketing, presentations, course-storytelling, building-agents) so
+   routing competes realistically.
+2. For each `should_trigger` prompt: feed it cold, record whether `constitution`
+   is the skill the agent loads. Run **3-5 trials** per prompt (fresh context).
+3. For each `should_not_trigger` prompt: confirm `constitution` does NOT load and
+   that the chosen skill matches `route_to`. Same 3-5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: >= 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the `harness`/`init` near-misses — those are the
+known traps, since "set up the project" reads close to "set the project's
+principles". A scaffolding-or-bootstrap prompt must not pull in `constitution`.
+
+## Capability eval
+
+Goal: prove the skill changes the answer, not just the routing.
+
+1. For the `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `constitution` loaded).
+   - **WITH** the `constitution` skill loaded.
+2. Grade each output against the `must_include` checklist — one point per
+   checkable item covered. A human or grading agent marks each present / absent.
+3. Compute coverage = `items_covered / total_items` for each run.
+
+**Pass bar: WITH the skill covers >= 80% of `must_include`; WITHOUT clearly
+lower** (target a >= 30-point gap). The discriminating behaviors are: the
+reconciliation pass against `02-DOCS/wiki/stack/*` (link, don't paste), testable
+numbered principles, the fixed authorship + decisions-logged principles,
+versioning + amendment log, the Definition-of-Done checklist, and explicit user
+ratification. A base agent typically writes a vague, unversioned wall of
+aspirations that duplicates the stack wiki — score that as a capability failure
+even if it reads tidy.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- The highest-signal capability check is reconciliation: a correct answer reads
+  the existing stack articles and LINKS them; it never pastes their config into
+  the constitution or silently resolves a contradiction between them.
+- Re-run after any edit to `SKILL.md` or `references/constitution-template.md` —
+  wording changes shift both triggering and rubric coverage.
+- Several `route_to` targets are ai-hub Spec-Kit phase siblings (`specify`, `plan`,
+  `analyze`, `sdd`) that ship alongside this skill; the near-misses here route
+  only to skills already present in the repo so the eval is runnable today.

package/skills/shared/constitution/evals/cases.yaml

@@ -0,0 +1,72 @@
+skill: constitution
+
+# Prompts that MUST load the `constitution` skill. It is the FIRST ai-hub Spec-Kit phase:
+# capture a project's non-negotiable principles (stack canon, quality bars,
+# conventions, branching/security/a11y floors) into .specify/memory/constitution.md,
+# reconciling with docs/stack/*. It NAMES bars and links enforcers; it does
+# not describe a feature (specify) or design an implementation (plan).
+should_trigger:
+  - prompt: "Let's set the non-negotiable principles for this project before we start building features."
+    why: "Capturing project-wide non-negotiables once, up front, is the exact purpose of the constitution phase."
+
+  - prompt: "I want a project constitution: stack canon, the quality bar, and our coding conventions in one place."
+    why: "Names the artifact and the three pillars (stack canon, quality bar, conventions) the skill produces."
+
+  - prompt: "We keep relitigating test coverage and branch naming — can we ratify these as project rules once and for all?"
+    why: "Turning repeatedly-relitigated decisions into ratified, enforceable principles is a core trigger, phrased without naming the skill."
+
+  - prompt: "Amend our engineering standards to require strict TypeScript and bump the version."
+    why: "Amending a ratified principle with a version bump is the amendment protocol this skill owns."
+
+  - prompt: "What's the definition of done for the whole repo that every PR has to pass?"
+    why: "The repo-wide Definition of Done (the merge bar verify runs against) lives in the constitution, not in any single feature spec."
+
+  - prompt: "Lock down our stack canon and quality floors so the SDD phases have guardrails to read."
+    why: "Explicitly the guardrail document every later SDD phase reads — the constitution's defining role."
+
+  - prompt: "Write our project's coding standards doc — formatter must pass clean, types strict, secrets never committed."
+    why: "These are enforceable project-wide non-negotiables (quality bar + security floor), the constitution's content."
+
+  - prompt: "Establecer las reglas del proyecto: convenciones de nombres, cobertura mínima y cómo hacemos los commits."
+    why: "Spanish phrasing for setting project-wide conventions, coverage floor, and commit rules — all constitution principles."
+
+# NEAR-MISS prompts that must NOT load `constitution`. Each routes to the genuinely
+# correct sibling that exists in this repo. The recurring trap: anything that sounds
+# like 'project setup' or 'standards' but is actually a feature, a stack mechanic,
+# the wiki scaffolding, or a security implementation.
+should_not_trigger:
+  - prompt: "Set up docs/tools and docs/ for this workspace and generate the root AGENTS.md."
+    route_to: "harness"
+    why: "Scaffolding the tooling + wiki layers and the Knowledge map is the harness's job; the constitution only writes one article INTO that wiki and links one row."
+
+  - prompt: "I'm starting from scratch and don't know where to begin — help me bootstrap the project."
+    route_to: "init"
+    why: "Front-door bootstrapping (ask the register question, write the profile, recommend bundles) is init; the constitution runs after the harness exists and the profile is set."
+
+  - prompt: "Show me how to actually configure Ruff and pytest with an 80% coverage gate in our FastAPI service."
+    route_to: "fastapi"
+    why: "The constitution NAMES the coverage bar; the concrete lint/test config is a stack mechanic owned by fastapi — the skill explicitly defers this."
+
+  - prompt: "Add input validation and proper authz to our login endpoint so it can't be abused."
+    route_to: "secure-coding"
+    why: "Implementing the security baseline is secure-coding; the constitution only ratifies the principle (e.g. 'authn/z baseline met') and links the enforcer."
+
+  - prompt: "Pick the type scale, color tokens, and spacing system for our app's design language."
+    route_to: "design"
+    why: "Choosing concrete design tokens is the design skill; the constitution at most names an accessibility floor and links wiki/stack/design.md."
+
+# Concrete tasks the skill should guide, with a rubric to grade WITH vs WITHOUT
+# the skill loaded. A skill-guided answer reconciles with the stack wiki, keeps
+# principles testable, includes the fixed authorship/decisions rules, versions
+# the file, and ratifies with the user — an ungrounded answer writes a vague,
+# unversioned wall of aspirations.
+capability:
+  - scenario: "Stand up the constitution for a new project that has a Next.js frontend and a FastAPI backend. The harness already wrote docs/stack/nextjs.md and fastapi.md with some conventions. There is a user-profile with the register: technical."
+    must_include:
+      - "Reads AGENTS.md and speaks in technical terms, briefly (one line of why per principle, few questions) rather than a long interview."
+      - "Runs the reconciliation pass: reads the existing wiki/stack/nextjs.md and fastapi.md, lifts only project-wide non-negotiables, and LINKS those articles instead of pasting their config; surfaces any contradiction for the user to resolve rather than auto-picking."
+      - "Every principle is numbered, imperative, and testable (a number, command, or named artifact), not an aspiration like 'write clean code'."
+      - "Includes the two fixed principles: git authorship is the human's (no Co-Authored-By AI / generated-with footer, enforced at ship) and significant decisions are logged."
+      - "Produces a Definition of Done checklist (the merge bar verify runs against) covering format/lint, types, tests/coverage, conventions, branch+PR+authorship, security, and decisions logged."
+      - "Writes .specify/memory/constitution.md with a version (v1.0.0), ratified date, and an append-only amendment log; adds the Knowledge-map row to root AGENTS.md additively (never deleting sections)."
+      - "Shows the draft and gets explicit ratification from the user before it takes effect, and ends by pointing to the specify phase as next in the chain."

package/skills/shared/constitution/references/constitution-template.md

@@ -0,0 +1,100 @@
+# Constitution template
+
+Render this into `02-DOCS/wiki/sdd/constitution.md`. Keep it to 1-2 screens. Every principle is one numbered, testable statement; link the `02-DOCS/wiki/stack/*` article or the script that enforces it rather than pasting the mechanic. Strike-and-replace on amendment — never silently edit a ratified principle.
+
+---
+
+```markdown
+---
+type: constitution
+title: <Project> — Constitution
+description: The non-negotiable principles every ai-hub Spec-Kit phase obeys.
+tags: [sdd, constitution]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: sdd
+version: v1.0.0
+---
+
+# <Project> — Constitution
+
+> Version: v1.0.0 · Ratified: YYYY-MM-DD · Last amended: YYYY-MM-DD
+> The non-negotiable principles every ai-hub Spec-Kit phase obeys. Stack mechanics live in
+> `02-DOCS/wiki/stack/*`; this file ratifies the principle and links the detail.
+
+## 1. Stack canon
+
+1. Primary language(s) and runtime: <e.g. TypeScript on Node 22, Python 3.12>. Pinned in
+   `<manifest>`. Detail: `02-DOCS/wiki/stack/<x>.md`.
+2. Frameworks fixed: <e.g. Next.js App Router, FastAPI>. Changing one is a MAJOR amendment.
+3. Package manager: <e.g. pnpm / uv>. One lockfile, committed.
+
+## 2. Quality bar
+
+4. Code is formatted and lint-clean on every commit (<formatter/linter>, zero warnings).
+   Enforced by `<pre-commit / CI step>` — detail in `02-DOCS/wiki/stack/<x>.md`.
+5. Types are <strict / checked>; the type checker passes with no errors before merge.
+6. Tests gate the merge: <TDD red→green→refactor>; line coverage ≥ <N>% on changed code.
+   Test tooling: `02-DOCS/wiki/stack/<x>.md`.
+
+## 3. Conventions
+
+7. Naming & structure: <directory layout, module boundaries, file naming>.
+8. API & errors: <error shape, status codes, response envelope> where applicable.
+9. Commit messages: <format, e.g. gitmoji + Conventional Commits — `✨ feat(scope): subject`>.
+
+## 4. Branching & shipping
+
+10. Work happens on a branch off `<default>`; merge via PR. Direct pushes to `<default>` are
+    not allowed.
+11. **Git authorship is the human's.** No `Co-Authored-By` an AI, no "generated with" footer.
+    Enforced at the `ship` phase.
+
+## 5. Security & privacy floor
+
+12. No secret is ever committed. Secrets load from `01-TOOLS/<provider>/.env` (gitignored).
+    Baseline: `secure-coding`.
+13. <authn/z baseline, data residency, dependency policy> as applicable.
+
+## 6. UX / accessibility floor (if there is a UI)
+
+14. Minimum accessibility bar: <e.g. WCAG 2.2 AA, keyboard-navigable, visible focus>.
+    Detail: `02-DOCS/wiki/stack/design.md`.
+
+## 7. Performance budgets (where they matter)
+
+15. <named budget, e.g. LCP ≤ 2.5s on the marketing site; p95 API latency ≤ 300ms>.
+
+## 8. Knowledge & decisions
+
+16. Every significant decision is appended to `02-DOCS/wiki/sdd/decisions.md` (date, options,
+    why). The constitution is the highest-order decision record.
+
+## Definition of Done (the merge bar `verify` runs against)
+
+A change ships only when ALL hold:
+
+- [ ] Formatter + linter clean (principle 4).
+- [ ] Type checker passes (principle 5).
+- [ ] Tests pass; coverage floor met on changed code (principle 6).
+- [ ] Conventions followed (principles 7-9).
+- [ ] On a branch, merged via PR, authored by the human (principles 10-11).
+- [ ] No secret committed; security baseline met (principles 12-13).
+- [ ] Accessibility / performance budgets met where they apply (principles 14-15).
+- [ ] Significant decisions logged (principle 16).
+
+## Amendment log (append-only)
+
+| Date | Version | Change | Why |
+|------|---------|--------|-----|
+| YYYY-MM-DD | v1.0.0 | Ratified initial constitution. | Project kickoff. |
+```
+
+---
+
+## Rendering notes
+
+- **Drop sections that don't apply.** No UI → drop §6. No hard perf budget → drop §7. Do not pad.
+- **Renumber on amendment carefully.** Prefer striking a principle (`~~10. …~~ (superseded by 17)`) and appending the new one over renumbering, so existing citations ("principle 10") stay valid.
+- **Version bump rules:** MAJOR = remove/reverse a principle; MINOR = add/tighten; PATCH = wording only.
+- **Link, don't paste.** Any concrete config (lint rules, pytest ini, Tailwind tokens) stays in `02-DOCS/wiki/stack/*`; the principle points to it.
+- **One screen test.** If the rendered file scrolls past ~2 screens, you are documenting, not legislating — move detail to the wiki.