From 6300d1596d4da71d389844700a75585031be43ba Mon Sep 17 00:00:00 2001 From: "pylot-app[bot]" Date: Mon, 20 Jul 2026 05:10:22 +0000 Subject: [PATCH] docs: upstream spec-kit improvements to consider (2026-07-20) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Automated scan of github/spec-kit v0.8.1→v0.13.0. Documents cherry-pickable command-template improvements: speckit.converge new command, hook enforcement directive, taskstoissues dedup fix, implement/constitution governance loads. Co-Authored-By: pylot-app[bot] <290870766+pylot-app[bot]@users.noreply.github.com> --- docs/upstream-improvements-2026-07-20.md | 113 +++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/upstream-improvements-2026-07-20.md diff --git a/docs/upstream-improvements-2026-07-20.md b/docs/upstream-improvements-2026-07-20.md new file mode 100644 index 0000000000..17d2909846 --- /dev/null +++ b/docs/upstream-improvements-2026-07-20.md @@ -0,0 +1,113 @@ +# Upstream spec-kit Improvements to Consider (2026-07-20) + +> Generated by automated spec-kit sync on 2026-07-20. +> Upstream: `github/spec-kit` | Current fork sync point: v0.8.1 | Upstream current: v0.13.0 + +## Upstream Status + +No bulk sync recommended — upstream v0.9–v0.13 made deep changes to the Python CLI, workflows engine, and +integration layer that are out of scope for our Claude-native fork. The items below are scoped to +command-template improvements that are directly applicable. + +--- + +## Recommended Cherry-Picks + +### 1. New command: `speckit.converge` (HIGH VALUE) + +**Upstream PR**: #3001 `feat: add /speckit.converge command` + +Assesses the current codebase against spec/plan/tasks and appends any remaining unbuilt work as new tasks +to `tasks.md` so `/speckit.implement` can complete it. Useful when implementation was interrupted or +partially completed. + +**Recommendation**: Add `templates/commands/converge.md` and a lean variant in `presets/lean/commands/` +with terse rewrite (≤40 lines per fork convention). + +--- + +### 2. Hook enforcement directive (MEDIUM VALUE) + +**Upstream PR**: #2901 `fix(extensions): tell agent to run mandatory hooks, not just emit the directive` + +All command templates now include an explicit instruction after each hook block: + +``` +After emitting the block above you MUST actually invoke the hook and wait for it to finish before +continuing. Run it the same way you would run the command yourself in this agent/session (the invocation +may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as +`/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. +``` + +Fixes a compliance gap where agents emit the hook directive but do not actually execute it. + +**Recommendation**: Cherry-pick into all 9 command templates. Low-risk, improves hook reliability. + +--- + +### 3. Fix: `speckit.taskstoissues` deduplication (HIGH VALUE) + +**Upstream PR**: #2992 `fix(taskstoissues): skip tasks that already have a GitHub issue` + +Before creating issues, the command now: +1. Adds `list_issues` to the `tools` frontmatter +2. Fetches all existing issues and matches against task IDs (`\bT\d{3}\b`) +3. Skips tasks that already have a matching issue and reports them + +Prevents duplicate issues when the command is re-run after tasks.md is regenerated. + +**Recommendation**: High-value fix. Cherry-pick into `templates/commands/taskstoissues.md`. + +--- + +### 4. Fix: `speckit.implement` loads constitution for governance (MEDIUM VALUE) + +**Upstream PR**: #2460 `Load constitution context in /speckit.implement to enforce governance` + +Adds a step to read `/memory/constitution.md` during context loading, so governance constraints are +enforced during code generation (consistent with how `checklist.md` and `taskstoissues.md` already load it). + +--- + +### 5. Fix: `speckit.constitution` — generalize command file scanning (MEDIUM VALUE) + +**Upstream PR**: #3418 `fix(templates): point constitution sync checklist at installed command files` + +The constitution sync checklist previously referenced `.specify/templates/commands/*.md` (upstream path). +Now scans for installed commands named `speckit.*` or `speckit-*` in the agent's actual commands directory +(e.g., `.claude/commands/`). Directly relevant to our Claude setup. + +--- + +### 6. Rename: `branch_numbering` → `feature_numbering` (LOW VALUE) + +`init-options.json` key `branch_numbering` is deprecated in favor of `feature_numbering`. The command emits +a deprecation warning if only `branch_numbering` is present. + +**Recommendation**: Low urgency — add warning when consumer repos actually use `branch_numbering`. + +--- + +## Already Applied + +- Checklist 6 named quality dimensions (Completeness/Clarity/Consistency/Measurability/Coverage/Edge Cases) + — cherry-picked in fellowship-dev fork PR #4. ✅ + +--- + +## Out of Scope + +- Python CLI changes (`py:` scripts, `scripts/python/` directory) — fork targets Claude/LLM agents, not the `specify` CLI +- Workflow engine changes (fan-out, fan-in, concurrency) +- Integration layer (Grok, Kiro, Azure DevOps, Firebender, OMP) +- Python git extension ports — bash scripts are intentional for this fork + +--- + +## Priority Order + +1. `speckit.converge` new command +2. `speckit.taskstoissues` dedup fix +3. Hook enforcement directive (all templates) +4. `speckit.implement` constitution load +5. `speckit.constitution` command scanning fix