fullstackgtm 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.25.0] — 2026-06-12
+
+### Added
+
+- **Agent skill distribution** — `npx skills add fullstackgtm/core` installs
+  [skills/fullstackgtm/SKILL.md](./skills/fullstackgtm/SKILL.md) into any
+  skills-compatible agent (Claude Code, Cursor, Codex, …): a compact operating
+  guide covering the governed audit → suggest → approve → apply loop, the
+  non-negotiable safety invariants, the verb map, and the credential ladder.
+  Documentation only — no runtime surface changes.
+
 ## [0.24.0] — 2026-06-12
 
 ### Added

package/README.md

@@ -27,7 +27,13 @@ Requires Node 20+. The core has zero runtime dependencies; only the MCP server e
 npx fullstackgtm doctor   # verify the install: node version, credentials, MCP peers, next step
 ```
 
-Installing for an AI agent? Hand it [INSTALL_FOR_AGENTS.md](./INSTALL_FOR_AGENTS.md) — a deterministic install-and-verify script with expected outputs. A documentation map lives in [llms.txt](./llms.txt).
+Installing for an AI agent? The fastest path is the agent skill:
+
+```bash
+npx skills add fullstackgtm/core   # Claude Code, Cursor, Codex, and other skills-compatible agents
+```
+
+It installs a compact operating guide ([skills/fullstackgtm/SKILL.md](./skills/fullstackgtm/SKILL.md)) — the governed loop, the safety invariants, and the verb map — so the agent reaches for plans instead of raw writes. For a deterministic install-and-verify script with expected outputs, hand it [INSTALL_FOR_AGENTS.md](./INSTALL_FOR_AGENTS.md). A documentation map lives in [llms.txt](./llms.txt).
 
 ## Five-minute loop
 

package/llms.txt

@@ -14,6 +14,7 @@ at/above `--fail-on`.
 
 - [README](https://github.com/fullstackgtm/core/blob/main/README.md): install, five-minute loop, auth ladder, MCP setup, programmatic use
 - [INSTALL_FOR_AGENTS](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md): deterministic install-and-verify steps with expected outputs
+- [Agent skill](https://github.com/fullstackgtm/core/blob/main/skills/fullstackgtm/SKILL.md): compact operating guide, installable via `npx skills add fullstackgtm/core`
 - [API reference](https://github.com/fullstackgtm/core/blob/main/docs/api.md): semver-covered surfaces — canonical model, rule interface, plan/apply contract, connector contract, config, CLI, MCP tools
 - [CRM-health lifecycle](https://github.com/fullstackgtm/core/blob/main/docs/crm-health-lifecycle.md): the Prevent → Detect → Remediate → Verify/Attribute model; no-new-dupes design
 - [CHANGELOG](https://github.com/fullstackgtm/core/blob/main/CHANGELOG.md): release history

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM",
@@ -30,6 +30,7 @@
     "CHANGELOG.md",
     "INSTALL_FOR_AGENTS.md",
     "llms.txt",
+    "skills",
     "LICENSE"
   ],
   "scripts": {

package/skills/fullstackgtm/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: fullstackgtm
+description: Govern CRM/GTM data operations through the fullstackgtm CLI — read-only hygiene audits, reviewable dry-run patch plans, deterministic value suggestions, and approval-gated write-back to HubSpot and Salesforce. Use when asked to audit, clean, dedupe, enrich, bulk-update, reassign, or write to a CRM; to gate record creation against duplicates; to parse, score, or link sales call transcripts; to map a competitive category; or to schedule any of the above. Never write to a CRM directly when this skill is available.
+---
+
+# fullstackgtm — plan/apply for your GTM stack
+
+Think `terraform plan` for the CRM: you may *read* everything, but every
+proposed change is a typed patch operation — object, field, before, after,
+reason, risk — that a human approves before any provider write happens.
+Connectors: HubSpot (read/write), Salesforce (read/write), Stripe (read-only).
+Requires Node 20+; every command below works zero-install via `npx`.
+
+## Non-negotiable invariants
+
+- `audit` and `suggest` never mutate anything. `apply` writes ONLY operation
+  ids explicitly passed via `--approve` (or a plan a human approved with
+  `plans approve`). Do not attempt to bypass this; surface the plan instead.
+- Operations whose value is a human decision carry `requires_human_*`
+  placeholders and are refused without a concrete `--value <opId>=<v>`
+  override. Never guess values — chain `suggest` (deterministic, evidence-
+  backed) and leave `low`/`create`/`none`-confidence entries to the human.
+- Secrets are never accepted as argv flags: env vars or stdin only
+  (`echo "$TOKEN" | fullstackgtm login hubspot`). Set `FSGTM_NO_BROWSER=1`
+  in headless environments.
+- Exit codes everywhere: `0` success, `1` error, `2` findings/matches at or
+  above the threshold (gate-shaped for scripts).
+
+## Verify the install, then prove the pipeline with zero credentials
+
+```bash
+npx fullstackgtm doctor --json        # node.ok: true + package.version
+npx fullstackgtm audit --demo --json  # dry-run plan over a seeded messy CRM
+```
+
+## The governed loop (the core of everything)
+
+```bash
+fullstackgtm audit --provider hubspot --save                  # read-only → saved plan id
+fullstackgtm suggest --plan-id <id> --provider hubspot --out suggestions.json
+fullstackgtm plans approve <id> --values-from suggestions.json  # high-confidence only
+fullstackgtm apply --plan-id <id> --provider hubspot          # writes ONLY approved ops
+```
+
+Credentials resolve in order: `--token-env <NAME>` → ambient env
+(`HUBSPOT_ACCESS_TOKEN`; `SALESFORCE_ACCESS_TOKEN` + `SALESFORCE_INSTANCE_URL`;
+`STRIPE_SECRET_KEY`) → stored `fullstackgtm login <provider>` → broker pairing.
+In a sandbox prefer the first two. LLM-powered verbs (`call parse`, `call
+score`, `market classify`) take `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`, or use
+their deterministic/worksheet fallbacks — the CLI never prompts when
+non-interactive.
+
+## Verb map
+
+| Verb | What it does |
+| --- | --- |
+| `resolve <contact\|account\|deal>` | Create gate: exit 0 = safe to create, 2 = exists/ambiguous — never blind-create |
+| `dedupe <object> --key <domain\|email\|name>` | One merge op per duplicate group, deterministic survivor; merges are irreversible |
+| `bulk-update <object> --where … --set\|--archive\|--create-task` | Filtered dry-run plan; filter re-verified per record at apply time |
+| `reassign --from <owner> --to <owner>` | Ownership handoff plans per object type |
+| `fix --rule <id>` | audit one rule → suggest → approve at the confidence bar → apply only with `--yes` |
+| `call parse\|score\|link\|plan` | Transcripts → evidence-quoted insights, rubric scorecards, deal linking, governed next-step writes |
+| `enrich append\|refresh\|ingest\|status` | Governed enrichment (Apollo pull / Clay ingest), fill-blanks-only plans |
+| `market capture\|classify\|worksheet\|observe\|fronts\|axes\|overlay\|scale\|report\|refresh` | Competitive category map; evidence quotes verified verbatim against stored captures |
+| `schedule add\|install\|run\|status` | Horizontal cron; read/plan-side allowlist only — scheduling NEVER auto-approves |
+| `plans list\|approve` / `snapshot` / `rules` / `doctor` | Plan lifecycle, raw snapshots, rule registry, machine state |
+
+All write-shaped verbs produce plans; none writes outside approve → apply.
+Add `--json` for machine-readable output on any command.
+
+## MCP server (alternative surface, same gates)
+
+```bash
+npx -y -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp
+```
+
+Tools over stdio: `fullstackgtm_audit` (read-only), `fullstackgtm_rules`,
+`fullstackgtm_suggest`, `fullstackgtm_call_parse`,
+`fullstackgtm_apply` (requires `approvedOperationIds`),
+`fullstackgtm_resolve`, `fullstackgtm_market_worksheet`,
+`fullstackgtm_market_observe`.
+
+## Going deeper
+
+- [llms.txt](https://github.com/fullstackgtm/core/blob/main/llms.txt) — the full invariant map per layer (calls, market, write verbs, enrich, schedule)
+- [INSTALL_FOR_AGENTS.md](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md) — deterministic install-and-verify with expected outputs
+- [docs/api.md](https://github.com/fullstackgtm/core/blob/main/docs/api.md) — semver-covered surfaces: canonical model, rule interface, plan/apply contract, connectors, config, CLI, MCP