mbertamini/harnessing-mistica

[brtbrt]

Why

mistica-web serves two audiences from one repo, and until now their AI
skills/docs were tangled together:

1. Library developers (us) — need authoring conventions, test internals, release
   steps. Should be active while working in this repo, and must NOT ship to consumers.
2. Library consumers (downstream apps) — get the mistica-react skill via
   npx skills add telefonica/mistica-web and read doc/llms.md from node_modules.
   Should ship, but must stay dormant in our own dev sessions.

Mixing them caused two problems:

• Consumer-facing docs/skills surfaced while we develop (wrong guidance, noise).
• Risk of internal dev docs leaking into the published npm tarball.

This PR cleanly separates the two "hats" by directory (controls auto-discovery) and
description: frontmatter (controls activation).

What changed

Audience	Skills	Docs	Active when…	Ships to npm?
Develop the library	.agents/skills/*	doc-internal/*	this repo is the open workspace	❌ excluded
Consume the library	published-skills/mistica-react/	doc/* (unchanged)	after npx skills add in a consumer repo	✅ docs ship; skill fetched from GitHub

Concretely:

• Added doc-internal/ — contributor-only docs (architecture.md,
  testing-internals.md, release-process.md). Excluded from the package.
• Added develop skills under .agents/skills/ (author-component,
  write-acceptance-test). Each references the relevant doc-internal/* file and is
  scoped to modifying mistica-web source.
• Moved the consumer skill to published-skills/mistica-react/, scoped to using the
  published package; it links only to shipped doc/ files.
• Added a root AGENTS.md with always-on "you are developing the library" guidance,
  pointing at doc-internal/.
• Updated package.json files / .npmignore so .agents/, published-skills/,
  and doc-internal/ are NOT shipped, while doc/ still is.
• Pointed the skills publisher at published-skills/mistica-react/ so
  npx skills add telefonica/mistica-web resolves the consumer skill from there.

What did NOT change

• Consumer docs in doc/ (llms.md, components.md, …) — untouched except for keeping
  links valid.
• The published package's public API and the consumer install flow
  (npx skills add telefonica/mistica-web) — same command, same result for downstreams.

How to verify

• Develop hat: open this repo as a workspace → only the develop skills auto-load;
  doc-internal/ is reachable via the skills / root AGENTS.md.
• Consume hat: from a separate consumer repo, run
  npx skills add telefonica/mistica-web → only mistica-react installs, and its links
  resolve to shipped doc/ files.
• No leakage: npm pack --dry-run (or yarn pack) shows doc/ present and
  .agents/, published-skills/, doc-internal/ absent.

Reviewer notes

• Key idea: "published to consumers" and "active while developing here" are
  independent — separated by folder, reinforced by mutually-exclusive description:
  triggers (USE-the-package vs MODIFY-the-source).
• Please sanity-check the package.json files/.npmignore diff and the
  npm pack --dry-run output — that's the guard against shipping internal docs.