From b2f81e47c03dee6cc8ebaf784fecbce334c235f7 Mon Sep 17 00:00:00 2001 From: "pylot-app[bot]" <290870766+pylot-app[bot]@users.noreply.github.com> Date: Mon, 27 Jul 2026 05:13:20 +0000 Subject: [PATCH 1/2] docs: add upstream sync recommendations (2026-07-27) Captures divergences between fellowship-dev/spec-kit templates/commands/ and upstream github/spec-kit, with cherry-pick recommendations for each. --- docs/upstream-sync-recommendations.md | 62 +++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/upstream-sync-recommendations.md diff --git a/docs/upstream-sync-recommendations.md b/docs/upstream-sync-recommendations.md new file mode 100644 index 0000000000..045eab4722 --- /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 + +All 9 command files in `templates/commands/` diverge from upstream. The divergences fall into five categories, each worth considering for upstream contribution. + +## 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` — Dedicated Setup Script + +**fellowship-dev divergence.** fellowship-dev references `scripts/bash/setup-tasks.sh` (and `setup_tasks.py`) instead of upstream's `check-prerequisites.sh`. This implies a dedicated setup flow for tasks. + +**Cherry-pick recommendation**: Verify `setup-tasks.sh` and `setup_tasks.py` exist and document why they diverge from the upstream prerequisite checker. If the dedicated scripts provide better task scaffolding, contribute them upstream with the script reference change. + +## 5. `taskstoissues.md` — `list_issues` MCP Tool + +**fellowship-dev addition.** fellowship-dev adds `github/github-mcp-server/list_issues` to the tools list. Upstream only has `issue_write`. The addition enables duplicate-detection before creating issues. + +**Cherry-pick recommendation**: Prevents duplicate GitHub issues during tasks-to-issues runs — a clear quality improvement. Open a PR to `github/spec-kit`. + +## Action Items + +- [ ] Contribute extension hook system documentation to `github/spec-kit` +- [ ] Contribute `checklist.md` quality dimension improvements upstream +- [ ] Contribute `constitution.md` scope guard upstream +- [ ] Clarify/contribute `tasks.md` dedicated setup script divergence +- [ ] Contribute `taskstoissues.md` `list_issues` tool addition upstream From ec3206000d98ad67dc5b8b66a09758dedaa336db Mon Sep 17 00:00:00 2001 From: "pylot-app[bot]" <290870766+pylot-app[bot]@users.noreply.github.com> Date: Mon, 27 Jul 2026 05:30:16 +0000 Subject: [PATCH 2/2] fix: correct factual inversions in upstream-sync-recommendations (review finding for #9) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Section 4: remove false claim that fellowship-dev uses setup-tasks.sh/setup_tasks.py; actual templates/commands/tasks.md uses check-prerequisites.sh, identical to upstream - Section 5: reverse direction of divergence for list_issues; upstream has it (PR #2992), fellowship-dev does not — reframe as cherry-pick FROM upstream INTO fellowship-dev - Update summary sentence and action items to match corrected facts Co-Authored-By: Claude Sonnet 4.6 --- docs/upstream-sync-recommendations.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/upstream-sync-recommendations.md b/docs/upstream-sync-recommendations.md index 045eab4722..45ce53dadf 100644 --- a/docs/upstream-sync-recommendations.md +++ b/docs/upstream-sync-recommendations.md @@ -5,7 +5,7 @@ ## Summary -All 9 command files in `templates/commands/` diverge from upstream. The divergences fall into five categories, each worth considering for upstream contribution. +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`) @@ -41,22 +41,22 @@ fellowship-dev/spec-kit has verbose, explicit instructions covering: **Cherry-pick recommendation**: This guardrail prevents scope creep in the constitution command. Strong upstream contribution candidate. -## 4. `tasks.md` — Dedicated Setup Script +## 4. `tasks.md` — No Meaningful Divergence -**fellowship-dev divergence.** fellowship-dev references `scripts/bash/setup-tasks.sh` (and `setup_tasks.py`) instead of upstream's `check-prerequisites.sh`. This implies a dedicated setup flow for tasks. +**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. -**Cherry-pick recommendation**: Verify `setup-tasks.sh` and `setup_tasks.py` exist and document why they diverge from the upstream prerequisite checker. If the dedicated scripts provide better task scaffolding, contribute them upstream with the script reference change. +**Action**: No upstream contribution needed for this file; the templates are aligned. ## 5. `taskstoissues.md` — `list_issues` MCP Tool -**fellowship-dev addition.** fellowship-dev adds `github/github-mcp-server/list_issues` to the tools list. Upstream only has `issue_write`. The addition enables duplicate-detection before creating issues. +**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**: Prevents duplicate GitHub issues during tasks-to-issues runs — a clear quality improvement. Open a PR to `github/spec-kit`. +**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 -- [ ] Clarify/contribute `tasks.md` dedicated setup script divergence -- [ ] Contribute `taskstoissues.md` `list_issues` tool addition 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