gsd-pi 2.74.0 → 2.75.0-dev.fd2382b9f

package/src/resources/extensions/gsd/workflow-templates/api-breaking-change.md

@@ -0,0 +1,117 @@
+# API Breaking Change Workflow
+
+<template_meta>
+name: api-breaking-change
+version: 1
+mode: markdown-phase
+requires_project: false
+artifact_dir: .gsd/workflows/api-breaks/
+</template_meta>
+
+<purpose>
+Remove or redesign a public API in a controlled way. Surveys all callers,
+migrates them, deprecates the old surface, and schedules the removal release.
+Built for APIs consumed by other modules in the repo AND by external
+dependents where feasible.
+</purpose>
+
+<phases>
+1. survey     — Identify all callers, draft the new design
+2. migrate    — Land the new API and migrate internal callers
+3. deprecate  — Mark the old API deprecated, communicate the change
+4. release    — Remove the old API in a future release
+</phases>
+
+<process>
+
+## Phase 1: Survey
+
+**Goal:** Understand the blast radius before touching anything.
+
+1. **Identify the old API:**
+   - What's the symbol/route/contract? Where is it defined?
+   - Is it internal-only, exported to the SDK, or a public network endpoint?
+
+2. **Map callers:**
+   - Internal: `grep` the symbol across the repo. List every call site with
+     file:line.
+   - External (if applicable): check the package registry for direct
+     dependents, look for GitHub code search results, check the docs.
+
+3. **Draft the new shape:**
+   - What's changing? (rename, signature change, semantic change?)
+   - What's the migration pattern for a typical caller?
+   - Can callers migrate incrementally, or is it all-or-nothing?
+
+4. **Produce `SURVEY.md`** with:
+   - Old signature vs new signature.
+   - Full caller list (internal + best-effort external).
+   - Migration difficulty per caller type.
+   - Timeline proposal: deprecate in release X, remove in release Y.
+
+5. **Gate:** Review the survey with the user. This is the "do we actually want
+   to do this?" checkpoint. Don't proceed if the blast radius is larger than
+   the benefit.
+
+## Phase 2: Migrate
+
+**Goal:** Land the new API and move internal callers to it.
+
+1. **Introduce the new API alongside the old one:**
+   - Export the new function/class/endpoint.
+   - The old API still works unchanged.
+   - Add tests for the new API.
+
+2. **Migrate internal callers:**
+   - One file at a time, atomic commits: `refactor(api): migrate <caller> to <new-api>`.
+   - Run tests after each batch.
+
+3. **Add a feature flag** if helpful — some callers may need runtime toggles
+   during a staged rollout.
+
+4. **Gate:** All internal callers migrated, tests green. Confirm before
+   proceeding to the deprecation phase.
+
+## Phase 3: Deprecate
+
+**Goal:** Tell external callers to migrate.
+
+1. **Mark the old API deprecated:**
+   - Add `@deprecated` JSDoc / language-equivalent annotations.
+   - Log a runtime deprecation warning on first use (if feasible and the
+     language supports it). Include the migration path in the message.
+
+2. **Update docs:**
+   - Changelog: a prominent `### Deprecated` section with migration guidance.
+   - README / API docs: note the deprecation timeline.
+   - If there's a `MIGRATIONS.md`, add an entry.
+
+3. **Communicate:**
+   - Draft a release-notes entry with before/after code examples.
+   - If the API has external users, draft an issue or blog post.
+
+4. **Ship** the deprecation release (coordinate with `/gsd workflow release`).
+
+5. **Gate:** Deprecation is live, callers have had time to migrate. Decide
+   the removal timeline (typically next minor or next major).
+
+## Phase 4: Release (removal)
+
+**Goal:** Delete the old API in a future release.
+
+1. **Verify ecosystem readiness:**
+   - Have internal consumers upgraded?
+   - Have known external consumers upgraded? If not, is it OK to force it?
+
+2. **Remove the old API:**
+   - Delete the deprecated code paths.
+   - Update tests.
+   - Update docs to remove references.
+
+3. **Release** as part of a major version bump (semver). Document the removal
+   prominently in the changelog.
+
+4. **Close the loop:** update `SURVEY.md` with the final outcome — what
+   shipped, what's still outstanding, any lessons learned.
+
+</process>

package/src/resources/extensions/gsd/workflow-templates/bugfix.md

@@ -3,6 +3,7 @@
 <template_meta>
 name: bugfix
 version: 1
+mode: markdown-phase
 requires_project: false
 artifact_dir: .gsd/workflows/bugfixes/
 </template_meta>

package/src/resources/extensions/gsd/workflow-templates/changelog-gen.md

@@ -0,0 +1,82 @@
+# Changelog Generator
+
+<template_meta>
+name: changelog-gen
+version: 1
+mode: oneshot
+requires_project: false
+artifact_dir: null
+</template_meta>
+
+<purpose>
+Generate a CHANGELOG entry (or release notes draft) from git commits since the
+last release tag. Categorizes by type, follows Keep a Changelog format, and
+writes to `CHANGELOG.md` (or prints if the user prefers).
+</purpose>
+
+<instructions>
+
+## 1. Locate the range
+
+- Find the last release tag: `git describe --tags --abbrev=0` (fall back to
+  the first commit if no tags exist).
+- Gather commits: `git log <last_tag>..HEAD --oneline --no-merges`.
+- If zero commits, say "No changes since <tag>" and stop.
+
+## 2. Categorize each commit
+
+Use the conventional-commit prefix when present:
+
+| Prefix                      | Category        |
+| --------------------------- | --------------- |
+| `feat:` / `feature:`        | Added           |
+| `fix:` / `bugfix:`          | Fixed           |
+| `refactor:`                 | Changed         |
+| `docs:`                     | Docs            |
+| `chore:` / `ci:` / `build:` | Maintenance     |
+| `perf:`                     | Performance     |
+| `BREAKING CHANGE` footer    | Breaking        |
+
+For commits without a prefix, infer the category from the subject line.
+
+## 3. Produce the entry
+
+Format using Keep a Changelog v1.1 conventions:
+
+```
+## [Unreleased] - YYYY-MM-DD
+
+### Added
+- <user-visible description> (#PR / commit sha)
+
+### Fixed
+- …
+
+### Changed
+- …
+
+### Breaking
+- …
+```
+
+- Prefer user-visible descriptions over commit-log verbatim.
+- Group breaking changes FIRST when present, even though the section appears later.
+- Omit empty sections.
+
+## 4. Write or print
+
+- If `CHANGELOG.md` exists, insert the new entry **after** the top-level
+  heading and before any existing `## [x.y.z]` entries. Do NOT touch prior
+  releases.
+- If it doesn't exist, create one with the standard Keep a Changelog header.
+- If the user's arguments include `--print`, print to the chat only — don't
+  write the file.
+
+## 5. Report
+
+End with:
+- the file path (or "printed, not written"),
+- the commit range used,
+- the number of commits processed per category.
+
+</instructions>

package/src/resources/extensions/gsd/workflow-templates/ci-bootstrap.md

@@ -0,0 +1,144 @@
+# CI Bootstrap Workflow
+
+<template_meta>
+name: ci-bootstrap
+version: 1
+mode: markdown-phase
+requires_project: false
+artifact_dir: .gsd/workflows/ci/
+</template_meta>
+
+<purpose>
+Set up continuous integration for a project that has none (or needs a rewrite).
+Picks a provider, builds a minimal working pipeline, and incrementally adds
+lint / test / build / deploy stages. Goal: green CI on the first PR after
+bootstrap, not a 2000-line yaml no one will maintain.
+</purpose>
+
+<phases>
+1. discover   — Understand the stack and what "passing" means today
+2. design     — Choose provider + plan the pipeline
+3. implement  — Land the config, fix local failures so CI passes
+4. verify     — Confirm the pipeline catches regressions
+</phases>
+
+<process>
+
+## Phase 1: Discover
+
+**Goal:** Know what to automate.
+
+1. **Detect the stack:**
+   - Primary language(s) and version(s) — check `package.json`, `pyproject.toml`,
+     `go.mod`, `Cargo.toml`, `.tool-versions`, `.nvmrc`.
+   - Package manager (npm / pnpm / yarn / pip / poetry / cargo / go).
+   - Test runner(s).
+   - Linter(s) / formatter(s).
+   - Build tool(s).
+
+2. **Run each check locally and record:**
+   - `<install command>` — does it complete?
+   - `<lint command>` — does it pass? How many warnings/errors?
+   - `<test command>` — does it pass? What's the duration?
+   - `<build command>` — does it pass? What's the output?
+
+   If any fails locally, CI will fail too. Record the failures honestly —
+   we'll triage in Phase 2.
+
+3. **Check existing CI config:**
+   - `.github/workflows/`, `.circleci/`, `.gitlab-ci.yml`, `azure-pipelines.yml`.
+   - Is something already there but disabled / broken?
+
+4. **Write `DISCOVERY.md`:**
+   - Stack summary.
+   - Current local-check status (pass/fail per step).
+   - Existing CI state.
+   - Constraints: open-source (free minutes matter), private, self-hosted?
+
+5. **Gate:** Confirm the discovery before spending time on CI config.
+
+## Phase 2: Design
+
+**Goal:** Pick a provider and shape the minimal viable pipeline.
+
+1. **Choose a provider.** Default to **GitHub Actions** if the repo is on
+   GitHub — it's the most portable and well-documented. Alternatives:
+   - GitLab CI for GitLab-hosted repos.
+   - CircleCI for existing infra / orb reuse.
+   - Ask before picking something else.
+
+2. **Plan the pipeline stages**:
+   - `install` — cache-friendly dependency install.
+   - `lint` — run linters (non-blocking? or blocking?).
+   - `test` — run tests (parallelize if the suite is slow).
+   - `build` — run the build (only if it produces a required artifact).
+   - `deploy` — optional, usually a later phase.
+
+3. **Decide triggers:**
+   - Pull requests to `main` — always.
+   - Pushes to `main` — yes, for post-merge verification.
+   - Nightly / cron — only if the project has flakes that need monitoring.
+
+4. **Plan caching** — this is what makes CI fast:
+   - Package manager caches (`node_modules`, `.venv`, `~/.cargo`).
+   - Build output caches (turborepo, bazel, etc.) if the project uses them.
+
+5. **Write `PLAN.md`:**
+   - Provider.
+   - Pipeline YAML sketch (high-level, not final).
+   - Jobs + their dependencies.
+   - Expected first-run duration (estimate).
+
+6. **Gate:** Confirm the plan. Scope creep on CI is very real.
+
+## Phase 3: Implement
+
+**Goal:** Land a green pipeline.
+
+1. **Write the CI config** — single file in the correct location.
+   - Use the latest stable syntax.
+   - Pin action versions by tag (`actions/checkout@v4`), not `latest`.
+   - Keep to one matrix axis unless there's a strong reason.
+
+2. **Triage local failures first.** If Phase 1 surfaced lint or test
+   failures, either fix them now or explicitly mark them as
+   `continue-on-error` (document why).
+
+3. **Iterate locally** using `act` for GitHub Actions if available, or push
+   to a feature branch and watch the run.
+
+4. **Commit atomically:**
+   ```
+   ci: add GitHub Actions pipeline (lint, test, build)
+   ```
+
+5. **Append notes to `IMPL.md`** — gotchas, action version picks, caching
+   decisions, any YAML tricks.
+
+## Phase 4: Verify
+
+**Goal:** Prove the pipeline catches what it should.
+
+1. **Green on main** — the pipeline must pass on the current `main`.
+
+2. **Red on a broken PR** — open a test PR that:
+   - Introduces a lint violation.
+   - Breaks a test.
+   - Breaks the build.
+   Confirm CI catches each one, then revert.
+
+3. **Check the timing** — total duration should be acceptable. If it's >15
+   min for a small project, look at caching and parallelization.
+
+4. **Document for contributors** — `CONTRIBUTING.md` (or equivalent):
+   - How to run each check locally.
+   - What the CI does.
+   - How to debug a red build.
+
+5. **Gate:** Final demo. Show the user:
+   - A green run on main.
+   - A red run on a deliberately-broken branch.
+   - The timing.
+   - The docs.
+
+</process>

package/src/resources/extensions/gsd/workflow-templates/dead-code.md

@@ -0,0 +1,81 @@
+# Dead Code Finder
+
+<template_meta>
+name: dead-code
+version: 1
+mode: oneshot
+requires_project: false
+artifact_dir: null
+</template_meta>
+
+<purpose>
+Find functions, files, and exports that appear unused. Report them with
+evidence. **Do not delete anything** — the human decides what's safe to remove.
+</purpose>
+
+<instructions>
+
+## 1. Identify the language & toolchain
+
+Inspect the repo root to determine the primary language. Based on that, pick
+the appropriate tooling:
+
+| Language        | Tool(s)                                                 |
+| --------------- | ------------------------------------------------------- |
+| TypeScript / JS | `ts-unused-exports`, `knip`, or manual `grep` fallback  |
+| Python          | `vulture`                                               |
+| Go              | `staticcheck` + manual dead-code detection              |
+| Rust            | `cargo +nightly udeps`, `cargo-machete`                 |
+| Other           | language-appropriate tool or manual symbol search       |
+
+If a suitable tool is installed in the project, use it. Otherwise fall back to
+a systematic manual search (see step 3).
+
+## 2. Scan for candidates
+
+Look for four kinds of dead code:
+1. **Unused exports** — exports no other file imports.
+2. **Unused files** — files imported by nothing (and not an entry point).
+3. **Dead branches** — functions that are reachable but have branches that
+   can never execute given the call sites.
+4. **Unused dependencies** — packages in `package.json` / `pyproject.toml`
+   that aren't imported anywhere.
+
+## 3. Verify each candidate
+
+Dead-code tools are noisy. Before reporting anything, manually confirm by:
+- Searching for the symbol name across the repo (`grep -r` or `rg`).
+- Checking build configs (webpack, vite, rollup) for dynamic imports.
+- Checking test configs for fixtures or test-only code.
+- Checking for usage in templates, strings, or dynamic accessors (these
+  often trip tools).
+
+If a symbol is only referenced in a test, distinguish:
+- Real dead code: test exists but production never calls it.
+- Test-only helper: legitimate — not dead.
+
+## 4. Bucket by confidence
+
+```
+## High confidence (safe to remove)
+- file path:line — symbol / file
+  Evidence: <why you're sure — zero refs, no dynamic import candidates, etc.>
+
+## Medium confidence (check with author)
+- file path:line — symbol
+  Evidence: <only referenced in one unclear place, or dynamic-import-lookalike>
+
+## Low confidence (ignore unless suspicious)
+- file path:line
+  Reason: <looks dead but could be a public API, plugin surface, etc.>
+```
+
+## 5. Don't delete
+
+End with:
+> To remove high-confidence items, run `/gsd workflow refactor "remove dead code"`
+> and pass the list above as context.
+
+The user decides. Do **not** delete files, `git rm`, or open a PR.
+
+</instructions>

package/src/resources/extensions/gsd/workflow-templates/dep-upgrade.md

@@ -3,6 +3,7 @@
 <template_meta>
 name: dep-upgrade
 version: 1
+mode: markdown-phase
 requires_project: false
 artifact_dir: .gsd/workflows/upgrades/
 </template_meta>

package/src/resources/extensions/gsd/workflow-templates/docs-sync.yaml

@@ -0,0 +1,76 @@
+# Docs Sync workflow — mode: yaml-step
+#
+# Iterate over undocumented public exports, write JSDoc / TSDoc / equivalent
+# for each, and verify the docs stay coherent with the code.
+
+version: 1
+name: docs-sync
+mode: yaml-step
+description: >-
+  Find undocumented public exports across the source tree, write
+  per-symbol documentation, and produce a summary of what changed.
+
+params:
+  src_glob: "src/**/*.ts"
+  doc_style: "TSDoc"
+
+steps:
+  - id: inventory
+    name: Inventory undocumented exports
+    prompt: >-
+      Scan {{src_glob}} for exported symbols (functions, classes, types,
+      constants) that lack a leading doc comment. Write one line per
+      undocumented export:
+
+        - <file_path>::<symbol_name> — <symbol kind>
+
+      Skip internal helpers, private exports, and generated code. If
+      everything is already documented, write "all documented" and no
+      list items. Save to `undocumented.md`.
+    requires: []
+    produces:
+      - undocumented.md
+    verify:
+      policy: content-heuristic
+      minSize: 1
+
+  - id: document
+    name: Document one export
+    prompt: >-
+      Add {{doc_style}} documentation to the symbol indicated by
+      {{_iter_capture_1}} (format: `<file_path>::<symbol_name>`).
+
+      - Describe what it does, not how.
+      - Document all parameters and the return type.
+      - Note any thrown errors or side effects.
+      - Keep it concise — one short paragraph + `@param` / `@returns`.
+
+      Append a log line to `docs-log.md`:
+      `- <symbol_name> — <file:line>`.
+    requires:
+      - inventory
+    context_from:
+      - inventory
+    produces:
+      - docs-log.md
+    iterate:
+      source: undocumented.md
+      pattern: "^- (.+::.+?) — "
+    verify:
+      policy: content-heuristic
+
+  - id: summary
+    name: Docs sync summary
+    prompt: >-
+      Produce a short summary at `docs-summary.md` listing: the total
+      number of exports documented, any that were intentionally skipped
+      with a reason, and a suggested follow-up (e.g. regenerate API docs
+      if the project has a generator).
+    requires:
+      - document
+    context_from:
+      - document
+    produces:
+      - docs-summary.md
+    verify:
+      policy: content-heuristic

package/src/resources/extensions/gsd/workflow-templates/env-audit.yaml

@@ -0,0 +1,88 @@
+# Env Audit workflow — mode: yaml-step
+#
+# Inventory every environment variable referenced across code/docs/CI, then
+# audit each one for drift (documented? default? required vs optional?
+# mentioned in CI?).
+
+version: 1
+name: env-audit
+mode: yaml-step
+description: >-
+  Find every environment variable the project uses and flag drift —
+  variables referenced in code but not in docs, or vice versa.
+
+params:
+  src_glob: "src/**/*.{ts,js,py,go,rb}"
+  ci_paths: ".github/workflows .circleci .gitlab-ci.yml"
+  doc_paths: "README.md docs/ .env.example"
+
+steps:
+  - id: inventory
+    name: Inventory env-var references
+    prompt: >-
+      Find every environment variable referenced in the project. Check:
+
+      - Code ({{src_glob}}): look for `process.env.X`, `os.environ["X"]`,
+        `os.Getenv("X")`, and equivalent patterns.
+      - Docs and `.env.example` ({{doc_paths}}).
+      - CI configs ({{ci_paths}}).
+
+      Produce `env-inventory.md` with one line per variable:
+
+        - <VAR_NAME> — code: <y|n>, docs: <y|n>, ci: <y|n>
+
+      Sort alphabetically. If any variable appears in one location but not
+      another, that's the drift — the next step will audit each entry.
+    requires: []
+    produces:
+      - env-inventory.md
+    verify:
+      policy: content-heuristic
+
+  - id: audit-var
+    name: Audit a single env variable
+    prompt: >-
+      Assess the env variable referenced by {{_iter_capture_1}} against
+      the three locations. For this variable, write an entry in
+      `env-audit.md`:
+
+        ## <VAR_NAME>
+        - Code refs: <file:line list>
+        - Documented: <yes — link | no — gap>
+        - CI: <yes | no>
+        - Required / optional: <deduced from usage>
+        - Has a default: <yes — value | no>
+        - Drift: <one of: none | undocumented | unused-in-code | missing-in-ci | conflicting-default>
+        - Recommendation: <one sentence>
+
+      If the variable is used only in third-party code we can't control,
+      note that and move on.
+    requires:
+      - inventory
+    context_from:
+      - inventory
+    produces:
+      - env-audit.md
+    iterate:
+      source: env-inventory.md
+      pattern: "^- ([A-Z][A-Z0-9_]+) — "
+    verify:
+      policy: content-heuristic
+
+  - id: report
+    name: Final drift report
+    prompt: >-
+      Produce `env-drift-report.md` summarizing:
+      - Variables with drift (by category: undocumented, unused, missing-in-ci).
+      - Recommended `.env.example` diffs to close the gaps.
+      - Any variables whose defaults or required-ness look wrong.
+
+      Keep it scannable — prioritize drift that could cause runtime failures.
+    requires:
+      - audit-var
+    context_from:
+      - audit-var
+    produces:
+      - env-drift-report.md
+    verify:
+      policy: content-heuristic

package/src/resources/extensions/gsd/workflow-templates/full-project.md

@@ -3,6 +3,7 @@
 <template_meta>
 name: full-project
 version: 1
+mode: auto-milestone
 requires_project: true
 artifact_dir: .gsd/
 </template_meta>

package/src/resources/extensions/gsd/workflow-templates/hotfix.md

@@ -3,6 +3,7 @@
 <template_meta>
 name: hotfix
 version: 1
+mode: markdown-phase
 requires_project: false
 artifact_dir: null
 </template_meta>