chore(speckit): install & customize Spec-Kit for dotCMS (legacy-aware, ADR-gated)

[nollymar]

What

Installs GitHub Spec-Kit v0.12.4 (Claude Code skills) into dotCMS/core and customizes it for dotCMS. Standard flow: /speckit-specify or /speckit-specify-fix → /speckit-plan → /speckit-tasks → /speckit-implement.

Why (dotCMS-specific requirements)

1. Legacy-aware — the codebase mixes modern com.dotcms.* and legacy com.dotmarketing.*; specs/plans must account for that, not assume greenfield.
2. ADRs feed the plan phase — ADRs live in the private repo dotCMS/platform-adrs; every /speckit-plan must consult relevant ones as binding input.
3. Spec-Kit never creates ADRs — it may only propose them; ADRs are authored in platform-adrs via its own new-adr.sh.
4. Two spec flows — separate templates/commands for new features vs. issue/bug resolution.

How

• Constitution (.specify/memory/constitution.md): legacy-aware principle + Critical Rules + ADR law (mandatory consultation, never-create guardrail). Loaded by every skill.
• ADR integration (upgrade-safe, no shipped files edited): read-only adr-context.sh (gh → platform-adrs/INDEX.md), /speckit-adr-context skill, a mandatory before_plan hook in extensions.yml, and an ADR Alignment gate in the plan-template override.
• Two flows: /speckit-specify (feature) + new /speckit-specify-fix (defect-framed issue template). Both funnel into /speckit-plan, so fixes get the ADR + legacy gates too.
• Upgrade-safety: customizations live in .specify/templates/overrides/ and net-new files; resolve_template prefers overrides/. See .specify/CUSTOMIZATIONS.md.

Verification

• resolve_template → overrides for spec/plan, issue template for the fix flow ✅
• adr-context.sh returns real ADRs (e.g. ADR-0009/0018) and exits 0 on no-match ✅
• extensions.yml valid YAML; create-new-feature.sh dry-run OK ✅
• Change set is additive (only CLAUDE.md modified) ✅
• Remaining manual check: a live /speckit-plan run to watch the before_plan hook fire end-to-end.

Note

Spec-Kit ships a native bug extension, intentionally not used because its assess→fix→test flow bypasses /speckit-plan (and thus the ADR gate). Rationale in .specify/CUSTOMIZATIONS.md.

🤖 Generated with Claude Code

This PR fixes: #36417

[claude]

Claude finished @nollymar's task in 48s —— View job

---

I'll analyze this and get back to you.

[github-actions]

🤖 dotBot Review (Bedrock)

Reviewed 7 file(s); 12 candidate(s) → 6 confirmed, 0 uncertain (unverified, kept for review).

⚠️ Coverage capped: 0 file(s) + 1 lower-severity candidate(s) skipped (limits: 40 files, 12 candidates).

Confirmed findings

• 🟠 High .claude/skills/speckit-analyze/SKILL.md:70 — Missing error handling for prerequisite script failure
  The script executes ./.specify/scripts/adr-context.sh and pipes to jq without checking the exit code. If adr-context.sh fails (e.g. network error accessing ADRs), the pipeline continues, potentially passing invalid JSON to jq and corrupting adr_data. PR verification notes it exits 0 on no-match but doesn't confirm error handling for other failures like gh command errors.
• 🟠 High .claude/skills/speckit-constitution/SKILL.md:47 — Pre-hook uses dotted command name instead of hyphenated version
  The EXECUTE_COMMAND in the mandatory pre-hook uses $command_name which retains dots (e.g. 'speckit.specify'), but shell scripts require hyphenated names (e.g. 'speckit-specify'). This mismatch will cause 'command not found' errors when the hook runs, breaking the ADR consultation gate.
• 🟡 Medium .claude/skills/speckit-adr-context/SKILL.md:45 — Command injection risk in ADR filename handling
  The script 'adr-context.sh' uses unquoted variables when processing ADR filenames (e.g. cat $adr_file), which could allow command injection if filenames contain spaces or special characters. While ADR numbers are numeric, the actual filenames might contain spaces if ADRs are renamed. Proper quoting of variables (e.g. "$adr_file") would mitigate this risk.
• 🟡 Medium .claude/skills/speckit-adr-context/SKILL.md:34 — Missing pre-flight checks for gh CLI availability and authentication state
  The script at .claude/skills/speckit-adr-context/SKILL.md line 34 runs gh issue view without first verifying the GitHub CLI is installed and authenticated. This could cause silent failures in environments without proper gh setup. While set -e catches errors, users would get unclear 'command not found' messages rather than explicit guidance to install/authenticate gh.
• 🟡 Medium .claude/skills/speckit-analyze/SKILL.md:135 — Constitution conflict detection lacks methodology
  The line 'Constitution conflict detection (if any)' in SKILL.md indicates conflict checks are part of the process but provides no methodology for how conflicts are detected between proposed changes and existing constitutional rules (legacy principles, ADRs). This creates risk of oversight as the detection mechanism isn't specified, relying on implicit understanding rather than documented checks against ADRs or legacy code constraints.
• 🟡 Medium .claude/skills/speckit-constitution/SKILL.md:84 — Consistency checks miss override directory templates
  The SKILL.md file's consistency check logic (line 84) only validates core template files but doesn't check for required override templates in .specify/templates/overrides/. This could allow invalid/missing override templates to go undetected, breaking template resolution that prioritizes overrides. grep shows the check uses find templates/ -name '*.md' which misses the overrides directory.

---

_{us.deepseek.r1-v1:0 · Run: #28641759022 · tokens: in: 78745 · out: 19648 · total: 98393 · calls: 25 · est. ~$0.212}

[nollymar]

Tracking task: #36417