diff --git a/docs/upstream-sync-recommendations.md b/docs/upstream-sync-recommendations.md new file mode 100644 index 0000000000..45ce53dadf --- /dev/null +++ b/docs/upstream-sync-recommendations.md @@ -0,0 +1,62 @@ +# Upstream Sync Recommendations + +> Auto-generated by spec-kit sync mission (2026-07-27). +> Compares fellowship-dev/spec-kit `templates/commands/` against upstream [github/spec-kit](https://github.com/github/spec-kit). + +## Summary + +The command files in `templates/commands/` were compared against upstream. The divergences fall into five categories (note: Section 4 was initially mis-reported; see correction inline). + +## 1. Extension Hook System (affects all commands except `checklist.md`) + +**fellowship-dev addition.** Where upstream uses a one-liner: + +``` +Run `hooks.before_analyze` from `.specify/extensions.yml` if present. +``` + +fellowship-dev/spec-kit has verbose, explicit instructions covering: +- YAML parsing and error handling +- `enabled` flag filtering +- `condition` expression skipping (deferred to HookExecutor) +- Distinct rendering blocks for optional vs. mandatory hooks + +**Cherry-pick recommendation**: If the `.specify/extensions.yml` hook system is production-stable, open a PR to `github/spec-kit` to contribute the extension hook documentation upstream. + +## 2. `checklist.md` — Quality Dimension Expansion + +**fellowship-dev improvement.** Upstream replaced the "unit tests for English" framing with a spec-quality validation approach. fellowship-dev adds: + +- Explicit six-dimension framework: **Completeness**, **Clarity**, **Consistency**, **Measurability**, **Coverage**, **Edge Cases** — each with a definition +- `[Spec §X.Y]` or `[Gap]` citation format for checklist item cross-references + +**Cherry-pick recommendation**: The expanded quality dimensions and citation format are clear improvements with no breaking changes. High-value upstream PR candidate. + +## 3. `constitution.md` — Scope Guard + +**fellowship-dev addition.** A new **Scope Guard** section explicitly prevents `constitution` from executing feature implementations, code generation, refactoring, or deployment requests. Instead it: +- Classifies every part of user input as either constitution content or a non-governance intent +- Defers non-governance intents to a `Next Actions` section +- Suggests the appropriate follow-up Spec Kit command for each deferred intent + +**Cherry-pick recommendation**: This guardrail prevents scope creep in the constitution command. Strong upstream contribution candidate. + +## 4. `tasks.md` — No Meaningful Divergence + +**No divergence found.** The actual `templates/commands/tasks.md` references `scripts/bash/check-prerequisites.sh`, identical to upstream. No dedicated `setup-tasks.sh` or `setup_tasks.py` scripts exist in this repo. + +**Action**: No upstream contribution needed for this file; the templates are aligned. + +## 5. `taskstoissues.md` — `list_issues` MCP Tool + +**Upstream addition fellowship-dev should adopt.** Upstream `github/spec-kit` (via upstream PR #2992) adds `github/github-mcp-server/list_issues` to the tools list, enabling duplicate-detection before creating issues. fellowship-dev/spec-kit currently only has `issue_write` and does not yet include `list_issues`. + +**Cherry-pick recommendation**: Cherry-pick `list_issues` FROM `github/spec-kit` INTO fellowship-dev/spec-kit. This upstream improvement prevents duplicate GitHub issues during tasks-to-issues runs — a clear quality improvement that fellowship-dev should adopt. + +## Action Items + +- [ ] Contribute extension hook system documentation to `github/spec-kit` +- [ ] Contribute `checklist.md` quality dimension improvements upstream +- [ ] Contribute `constitution.md` scope guard upstream +- [ ] `tasks.md` — no action needed (templates already aligned with upstream) +- [ ] Cherry-pick `list_issues` MCP tool FROM `github/spec-kit` INTO fellowship-dev/spec-kit