write-spec skill (and templates/skills/ surface) not installed or updated by upgrade/init process

[markhazleton]

Summary

The write-spec skill (and the entire templates/skills/ surface introduced in v2.4.0) is not installed or updated by any part of the upgrade or install process. Consumers who upgrade to v2.4.0 do not receive the skill, even though the updated devspark.specify command now delegates to it.

This was discovered during an upgrade from v2.1.0 → v2.4.0 using the /devspark.upgrade agent prompt. After the upgrade completed successfully (28 commands, 21 scripts updated, VERSION stamped), the write-spec skill was entirely absent.

---

What Is Missing

The following paths exist in the DevSpark source repo under templates/skills/ but are never written to a consumer project:

.devspark/templates/skills/write-spec/SKILL.md          ← missing
.devspark/templates/skills/write-spec/scripts/           ← missing
.devspark/templates/skills/write-spec/references/        ← missing
.devspark/templates/skills/ADAPTER-contract.md           ← missing
.devspark/templates/skills/SKILL-validation-contract.md  ← missing
.devspark/templates/skills/README.md                     ← missing

---

Where It Breaks

1. /devspark.upgrade agent prompt

The upgrade prompt (devspark.upgrade.md) — both the stock default and the documented manual procedure — only covers:

• .devspark/defaults/commands/ (command templates)
• .devspark/scripts/ (PowerShell/Bash scripts)
• .devspark/VERSION (version stamp)
• Agent shims (.github/agents/, .github/prompts/, etc.)

There is no mention of .devspark/templates/skills/ anywhere in the upgrade prompt. The "Framework-owned (safe to overwrite on upgrade)" section does not list the skills directory.

2. devspark init / quickstart guides

The quickstart guides and devspark init logic do not scaffold the skills directory into new consumer projects.

3. generate-atomic-shims.ps1 / update-agent-context.ps1

These scripts operate on commands only and have no awareness of the skills surface.

---

Impact

• devspark.specify (v2.4.0) states it delegates spec-drafting to the write-spec skill via the adapter contract. Consumers who upgrade get the thin-wrapper specify.md but not the skill it wraps, silently degrading to fallback behavior with no warning.
• There is no validation step in the upgrade flow that checks for missing skills.
• The "Verify Framework Files" step (Step 6) in the upgrade prompt does not enumerate skills as expected files.

---

Expected Behavior

After running /devspark.upgrade or devspark upgrade:

1. All files under templates/skills/ in the DevSpark source should be written to .devspark/templates/skills/ in the consumer project.
2. The upgrade prompt's "Framework-owned" file list should include .devspark/templates/skills/.
3. Step 6 (Verify Framework Files) should check that skills referenced by command prompts are present.
4. If a skill is missing, the upgrade should report it as MISSING: with the same severity as a missing script.

---

Suggested Fix

In templates/commands/upgrade.md

Add to the Framework-owned (safe to overwrite on upgrade) section:

- `.devspark/templates/skills/` — portable Agent Skill packages (SKILL.md + scripts)

Add to Step 7a. Update stock defaults:

Write the latest skill packages to `.devspark/templates/skills/`. This directory
is framework-owned and safe to overwrite completely.

In upgrade scripts

Any script that performs the mechanical upgrade should also sync templates/skills/ from upstream.

In devspark init / quickstart guides

Scaffold .devspark/templates/skills/ during initial installation, mirroring the same content.

In Step 6 (Verify Framework Files)

Add a check for each skill referenced by installed commands:

MISSING: .devspark/templates/skills/write-spec/SKILL.md

---

Workaround (Applied)

The skill was manually installed by fetching directly from GitHub raw content:

New-Item -ItemType Directory -Force -Path ".devspark\templates\skills\write-spec"
Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/markhazleton/devspark/main/templates/skills/write-spec/SKILL.md" `
  -OutFile ".devspark\templates\skills\write-spec\SKILL.md"

This should not be necessary — the upgrade process should handle it automatically.

---

Environment

• Upgrade method: /devspark.upgrade agent prompt (GitHub Copilot)
• Previous version: 2.1.0 (2026-04-20, method: claude-quickstart)
• Target version: 2.4.0 (2026-05-20)
• Platform: Windows / PowerShell 7

[markhazleton]

Resolved in b03261a (on main).

Quickstart fix: Added Step 5.5 "Pull Agent Skills" to all 5 quickstart guides (copilot, claudecode, cursor, codex, generic), fetching templates/skills/** into .devspark/templates/skills/ with required file-presence validation.

Upgrade fix: templates/commands/upgrade.md now lists .devspark/templates/skills/ under Framework-owned; Step 7a re-syncs skill packages; Step 6 reports missing skill files at the same severity as missing scripts; post-upgrade summary surfaces a stock skills/ row. Copilot quickstart upgrade-mode and repair-mode step lists also include Step 5.5.

Regression guard: tests/test_skills_install_contract.py (8 cases) asserts every quickstart references .devspark/templates/skills/, fetches write-spec/SKILL.md, and that upgrade.md keeps skills in the Framework-owned section.

Note: the update-agent-context.{sh,ps1} skill-presence reporting and explicit repo-local-vs-host-level skill docs ($CODEX_HOME/skills/) are deferred and can be filed as separate follow-ups if needed.