publish-templates

name

publish-templates

description

Publish a battle-tested specflow template by writing it to the canonical source (`src/markdown/templates/{name}.md`), regenerating the matching DocVault KB snapshot guide page, building, testing, committing, pushing, and stopping before `npm publish` for manual passkey auth. The canonical source IS `src/markdown/templates/`; the DocVault guide pages are derived KB snapshots, not editable sources. Mandatory backup-before-edit. Triggers on "publish templates", "ship template changes", "promote template", "sync templates to npm", "publish a template".

/publish-templates — Battle-tested template → npm publish pipeline

Why this skill exists

specflow templates ship via npm and are read by the MCP server at runtime. To get a template change into users' hands, the change MUST land in src/markdown/templates/{name}.md in the specflow repo and then go through npm publish. This skill automates that pipeline and keeps the human-readable DocVault snapshot in sync as a side effect.

Source of truth (HARD — read this twice)

INPUT: a battle-tested template (from a user-level location, project override,
       or wherever the template was iterated)
                       │
                       │  /publish-templates: sanitize, make project-agnostic
                       ▼
src/markdown/templates/{name}.md       ← CANONICAL SOURCE (specflow git repo)
                       │                  This is what ships. This is committed
                       │                  to the specflow git repo. Edit here
                       │                  (or via this skill from another source).
                       │
              ┌────────┴─────────┐
              │                  │
              ▼                  ▼  (regenerated as a side effect of this skill)
   npm run build           DocVault/Projects/SpecFlow/Templates/{name}-guide.md
              │                     ↑ KB snapshot — codeblock + frontmatter +
              ▼                       changelog. NOT editable. NOT a source.
   dist/markdown/templates/        Humans read this in Obsidian to understand
              │                     the template. Agents NEVER read it at runtime.
              ▼                     The codeblock is regenerated from src/ on
   npm publish (passkey, manual)   every publish — hand-edits get overwritten.
              │
              ▼
   @lbruton/specflow on npm
              │
              ▼  (next MCP boot)
   DocVault/specflow/{project}/templates/{name}.md
              ↑ runtime cache, overwritten on every boot from the bundled
                npm package. Editing here is pointless — it gets clobbered.

Three rules that follow from this:

1. src/markdown/templates/{name}.md is the ONLY editable source. Do not edit the guide pages by hand. Do not edit the runtime cache. Do not treat the DocVault Projects/SpecFlow/Templates/ folder as a source — it's a published mirror that gets regenerated on every publish.
2. The guide pages are regenerated by this skill. This skill replaces their ## Canonical Content codeblock with the current src/ content on every publish, updates last_synced and specflow_version frontmatter, and appends a Change Log entry. Hand-edits to those sections will be silently overwritten by the next publish.
3. The runtime cache at DocVault/specflow/{project}/templates/ is read-only. It's an artifact of the MCP boot process, not part of the publish flow. NEVER edit it.

If you find drift between src/markdown/templates/{name}.md and the matching guide page, src/ is canonical — the guide page is stale and should be regenerated by running this skill. Each guide page even says so in its own frontmatter (canonical_source: src/markdown/templates/...) and in its "Canonical Source" section.

Why the previous version of this skill had the direction wrong

The pre-2026-04-07 version of this skill documented the flow as DocVault guide → src/markdown/templates/, treating the guide page codeblock as the editable source. That was a leftover from an early INC-002 recovery model that never actually worked end-to-end (if it had ever been run, nothing would have shipped to npm because the skill wasn't writing to the right place). The DocVault guide pages themselves always documented src/ as canonical — only the skill body got it backwards. Fixed 2026-04-07. If you're reading an older mem0 entry or commit message that suggests the opposite direction, the older entry is wrong.

---

When to run this skill

Run this skill when you have a template change that you want to ship to users. The template change can come from anywhere — typical sources:

• A template that was iterated at the user level in a working session and is now stable
• A project-specific override that turned out to be generally useful and should be promoted to the global template
• A direct hand-edit to src/markdown/templates/{name}.md that needs to flow through to the guide page snapshot and to npm

Do NOT run this skill for routine spec creation — it's for publishing template changes, not for using templates.

---

Steps

Step 1 — Identify the source

Ask the user (or detect from context) which template is being published and where the new content is coming from. The source can be:

• A path to a working file (e.g., ~/.claude/skills/.../my-improved-template.md)
• A project override (e.g., DocVault/specflow/StakTrakr/templates/{name}.md)
• A direct edit already made to src/markdown/templates/{name}.md

Confirm with the user which template name (one of the 10 canonical templates) and what the change is, in one sentence. The canonical 9 are:

code-quality-reviewer-template.md   product-template.md
design-template.md                  requirements-template.md
implementer-prompt-template.md      spec-reviewer-template.md
structure-template.md               tasks-template.md
tech-template.md

Step 2 — Backup BOTH directories (MANDATORY — STOP if backup fails)

DATE=$(date +%Y-%m-%d_%H%M%S)
BACKUP_DIR=~/Nextcloud/Backups/specflow-templates
mkdir -p "$BACKUP_DIR"

# Backup canonical src/
cd ${SPECFLOW_REPO}
zip -r "$BACKUP_DIR/specflow-src-templates-$DATE.zip" src/markdown/templates/
ls -lh "$BACKUP_DIR/specflow-src-templates-$DATE.zip"

# Backup DocVault guide pages (so we can recover the changelog history if regen breaks)
cd ${DOCVAULT_PATH}
zip -r "$BACKUP_DIR/specflow-docvault-templates-$DATE.zip" "Projects/SpecFlow/Templates/"
ls -lh "$BACKUP_DIR/specflow-docvault-templates-$DATE.zip"

If either zip fails or the file isn't created, STOP. Do not proceed without working backups. This rule exists because INC-002 and the 2026-04-07 recovery sprint both could have been avoided with a single pre-edit snapshot.

Step 3 — Sanitize and write to canonical src/

Read the source (from Step 1). Identify and strip any project-specific bits:

• Hardcoded project names (StakTrakr, HexTrackr, etc.) → generic placeholders
• Hardcoded paths to /Volumes/DATA/GitHub/<project>/ → relative paths or <workflowRoot> placeholders
• User-specific preferences (lbruton's personal style choices) → reasonable defaults
• References to skills/tools that aren't part of the public specflow distribution

Show the user the sanitized version BEFORE writing. Get a one-line confirmation. Then write to src/markdown/templates/{name}.md.

If the file already contains the same content (no-op publish), STOP and report "src/ is already in sync with the source — nothing to publish."

Step 4 — Regenerate the matching DocVault guide page

For src/markdown/templates/{name}.md, find the matching guide page at DocVault/Projects/SpecFlow/Templates/{name}-guide.md. Regenerate it:

1. Preserve the existing frontmatter except update:
   • last_synced: <today, YYYY-MM-DD>
   • specflow_version: <new version> (you'll know the new version after Step 6 — for now write a placeholder, then come back and fix it after the bump)
2. Preserve the existing prose sections (## Purpose, ## Used By, ## Canonical Source).
3. Replace the ## Canonical Content codeblock contents with the new src/ content verbatim. Keep the ```markdown ... ``` fences. Everything between the fences gets replaced.
4. Append a new entry to the ## Change Log section (create the section before the end of the file if it doesn't exist):

   ## Change Log
   
   - **<YYYY-MM-DD>** — v<new version> — <one-line description of what changed and why>
   

If the guide page doesn't exist for this template (rare — only for brand-new templates), create it from scratch with the full expected structure (frontmatter, Purpose, Used By, Canonical Source, Canonical Content, Change Log). Read another guide page like requirements-template-guide.md for a structural reference.

Step 5 — Diff check

cd ${SPECFLOW_REPO}
git diff --stat src/markdown/templates/

cd ${DOCVAULT_PATH}
git diff --stat "Projects/SpecFlow/Templates/"

If neither has changes, STOP and report "Nothing to publish — both repos already in sync." Otherwise, show the diffs to the user before continuing.

Step 6 — Build, test, bump version

cd ${SPECFLOW_REPO}
npm run build 2>&1 | tail -20
npm test 2>&1 | tail -10

Both must succeed. If either fails, STOP and report the failure — do not proceed with a broken build.

Then bump the patch version. Use the Edit tool with a precise old_string match against package.json to avoid touching anything else. Then refresh the lockfile:

npm install --package-lock-only 2>&1 | tail -5

Now go back to Step 4 and update the guide page frontmatter specflow_version field with the actual bumped version, then re-stage.

Step 7 — Commit specflow repo

cd ${SPECFLOW_REPO}
git add src/markdown/templates/ package.json package-lock.json
git commit -m "$(cat <<'EOF'
feat(templates): publish <name> v<new version>

<one-line description of what changed and why>

Source: <where the battle-tested template came from>
Backup: ~/Nextcloud/Backups/specflow-templates/specflow-src-templates-<DATE>.zip

Co-Authored-By: Claude Opus 4.6 (1M context) <[e-mail]>
EOF
)"
git push origin main

Direct push to main is fine for specflow — repo policy allows it. The push is required BEFORE npm publish so the published package can be cross-referenced against the git SHA.

Step 8 — Commit DocVault repo

cd ${DOCVAULT_PATH}
git add "Projects/SpecFlow/Templates/<name>-guide.md"
git commit -m "docs(SpecFlow): regenerate <name>-guide for v<new version>"
git push origin main

DocVault commits also go direct to main. The DocVault commit happens AFTER the specflow commit so the guide page's specflow_version field always points to a real published git SHA on the specflow side.

Step 9 — STOP for manual npm publish

✅ Build, test, commit, and push complete. Version bumped to <new>.

⏸ STOPPING for manual npm publish (passkey required).

Run this in your terminal:
  cd ${SPECFLOW_REPO} && npm publish --access public

When you've published, tell me and I'll verify + clear the npx cache.

This system uses passkey authentication for npm. The skill CANNOT run npm publish directly — it fails with 401 at the auth step. Hand off to the user, wait for explicit confirmation, do not assume success or retry from inside the skill.

Step 10 — Verify and clear npx cache

After the user confirms publish:

npm view @lbruton/specflow version
# Should show the new version. If it shows old, wait 30s and retry once.

# Clear stale npx cache so the next MCP boot pulls the new version:
find ~/.npm/_npx -path "*/specflow/package.json" -exec dirname {} \; 2>/dev/null | xargs -I{} rm -rf {}
echo "npx cache cleared"

Step 11 — Report

## Template published 🟢

**Template:** <name>
**Version:** <old> → <new>
**Backups:**
  - <path>/specflow-src-templates-<date>.zip
  - <path>/specflow-docvault-templates-<date>.zip
**Specflow commit:** <SHA> (pushed to origin/main)
**DocVault commit:** <SHA> (pushed to origin/main)
**npm:** @lbruton/specflow@<new version>
**npx cache:** cleared

The next MCP boot in any project will pick up the new template automatically.

---

Failure modes and recovery

Failure	What to do
Backup zip not created	STOP. Check Nextcloud mount, disk space, perms. Do not proceed without backups.
Source file from Step 1 not found	STOP. Ask the user to clarify the source path.
Sanitization removes too much / too little	Show the user, ask for guidance, do not auto-decide.
npm run build fails	STOP. Show the build error. Do not commit broken src/. Investigate the TypeScript or template-loading code.
npm test fails	STOP. Show the test failures. If it's a template-content test, decide whether to update the test or revert the template change.
Guide page regen produces invalid markdown (e.g., codeblock fence mismatch)	STOP. Restore the guide page from specflow-docvault-templates-<date>.zip. Investigate the regen logic before retrying.
git push rejected (specflow)	Pull rebase, resolve, re-push manually. Do not auto-rebase from inside the skill.
npm publish returns 401/404	Expected — passkey constraint. Hand off to user. Don't retry from the skill.
npm view shows old version after publish	Wait 30s, retry once. If still old, npm propagation lag — continue and verify on next session.
User reports wrong content shipped	Restore canonical src/ from specflow-src-templates-<date>.zip, restore guide pages from specflow-docvault-templates-<date>.zip, bump patch, republish with corrected source.

---

What this skill does NOT do

• Does not edit DocVault guide pages by hand. Guide pages are regenerated, never hand-edited. Hand-edits to the codeblock or frontmatter will be silently overwritten on the next publish.
• Does not edit DocVault/specflow/{project}/templates/. That's the runtime cache, overwritten on every MCP boot.
• Does not run npm publish. Passkey auth prevents this. User runs it manually.
• Does not handle multi-template publishes in one run. Run the skill once per template. If you need to publish 3 templates at once, run it 3 times — each gets its own version bump and changelog entry.
• Does not validate template content semantically. It will publish whatever you put in src/markdown/templates/{name}.md. Bad templates ship as fast as good ones — the user-level battle-test is the only quality gate.
• Does not deal with project overrides. Project-level templates at DocVault/specflow/{project}/templates/ are completely separate from the global publish flow. If you're customizing a single project's template, edit that file directly — don't run this skill.

Related

• DocVault/Projects/SpecFlow/Templates/README.md — KB snapshot index page (the human-readable mirror landing page)
• DocVault/Projects/SpecFlow/recovered-templates-2026-04-07/ — forensic backup from the 2026-04-07 recovery sprint
• mem0: feedback_npm_publish_passkey.md — passkey constraint rationale
• specflow CLAUDE.md § "Templates — Source of Truth Hierarchy" — must match this skill's source-of-truth model. If they ever drift, fix both in the same edit.