54e6da3126
* fix(#2767): pass paths via --files to gsd-sdk query commit + lint guard Workflows, agents, commands, and references passed file paths positionally to `gsd-sdk query commit`, which silently appended them to the commit subject and triggered the `.planning/` wholesale-stage fallback in sdk/src/query/commit.ts:136. Regression of #733/#798. Inserted `--files` before the path list at every site (81 invocations across 50 files). Added tests/bug-2767-gsd-sdk-commit-files-flag.test.cjs as a permanent lint that scans every shipped .md file and asserts each `gsd-sdk query commit[-to-subrepo]` invocation either uses `--files` or carries no path arguments. Closes #2767 * test(#2767): replace source-grep with behavioral SDK test The original test walked every shipped .md file and regex-tokenized `gsd-sdk query commit` invocations to assert `--files` was present. CONTRIBUTING.md prohibits this source-grep pattern. Rewrite as behavioral SDK tests against `sdk/dist/cli.js` over a real tmp git project (createTempGitProject helper). Cover both the well-formed (`--files <paths>`) form — clean subject, exactly-staged files, .planning/ left untouched — and the buggy positional form, asserting the documented misbehavior (paths leak into subject + the `.planning/` wholesale-stage fallback at commit.ts:136). Also asserts `commit-to-subrepo` rejects when `--files` is omitted (commit.ts:258). The doc-lint is retained as a supplementary defense-in-depth guard since agent-prompt markdown invocations cannot be exercised end-to-end — but it is no longer the primary contract. * docs(#2767): correct contradictory --files guidance in zh-CN/en docs + fix test docstring
80 lines
2.3 KiB
Markdown
80 lines
2.3 KiB
Markdown
---
|
|
name: gsd:add-backlog
|
|
description: Add an idea to the backlog parking lot (999.x numbering)
|
|
argument-hint: <description>
|
|
allowed-tools:
|
|
- Read
|
|
- Write
|
|
- Bash
|
|
---
|
|
|
|
<objective>
|
|
Add a backlog item to the roadmap using 999.x numbering. Backlog items are
|
|
unsequenced ideas that aren't ready for active planning — they live outside
|
|
the normal phase sequence and accumulate context over time.
|
|
</objective>
|
|
|
|
<process>
|
|
|
|
1. **Read ROADMAP.md** to find existing backlog entries:
|
|
```bash
|
|
cat .planning/ROADMAP.md
|
|
```
|
|
|
|
2. **Find next backlog number:**
|
|
```bash
|
|
NEXT=$(gsd-sdk query phase.next-decimal 999 --raw)
|
|
```
|
|
If no 999.x phases exist, start at 999.1.
|
|
|
|
3. **Add to ROADMAP.md** under a `## Backlog` section. If the section doesn't exist, create it at the end.
|
|
Write the ROADMAP entry BEFORE creating the directory — this ensures directory existence is always
|
|
a reliable indicator that the phase is already registered, which prevents false duplicate detection
|
|
in any hook that checks for existing 999.x directories (#2280):
|
|
|
|
```markdown
|
|
## Backlog
|
|
|
|
### Phase {NEXT}: {description} (BACKLOG)
|
|
|
|
**Goal:** [Captured for future planning]
|
|
**Requirements:** TBD
|
|
**Plans:** 0 plans
|
|
|
|
Plans:
|
|
- [ ] TBD (promote with /gsd-review-backlog when ready)
|
|
```
|
|
|
|
4. **Create the phase directory:**
|
|
```bash
|
|
SLUG=$(gsd-sdk query generate-slug "$ARGUMENTS" --raw)
|
|
mkdir -p ".planning/phases/${NEXT}-${SLUG}"
|
|
touch ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
|
|
```
|
|
|
|
5. **Commit:**
|
|
```bash
|
|
gsd-sdk query commit "docs: add backlog item ${NEXT} — ${ARGUMENTS}" --files .planning/ROADMAP.md ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
|
|
```
|
|
|
|
6. **Report:**
|
|
```
|
|
## 📋 Backlog Item Added
|
|
|
|
Phase {NEXT}: {description}
|
|
Directory: .planning/phases/{NEXT}-{slug}/
|
|
|
|
This item lives in the backlog parking lot.
|
|
Use /gsd-discuss-phase {NEXT} to explore it further.
|
|
Use /gsd-review-backlog to promote items to active milestone.
|
|
```
|
|
|
|
</process>
|
|
|
|
<notes>
|
|
- 999.x numbering keeps backlog items out of the active phase sequence
|
|
- Phase directories are created immediately, so /gsd-discuss-phase and /gsd-plan-phase work on them
|
|
- No `Depends on:` field — backlog items are unsequenced by definition
|
|
- Sparse numbering is fine (999.1, 999.3) — always uses next-decimal
|
|
</notes>
|