@tekyzinc/gsd-t 2.8.1 → 2.10.0

package/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to GSD-T are documented here. Updated with each release.
+
+## [2.10.0] - 2026-02-10
+
+### Added
+- `CHANGELOG.md` release notes document with full version history
+- `changelog` CLI subcommand — opens changelog in the browser (`gsd-t changelog`)
+- Clickable version links in CLI output (OSC 8 hyperlinks to changelog)
+- `checkin` command now auto-updates CHANGELOG.md on every version bump
+- `update-all` now creates CHANGELOG.md for registered projects that don't have one
+
+## [2.9.0] - 2026-02-10
+
+### Added
+- `gsd-t-setup` command — generates or restructures project CLAUDE.md by scanning codebase, detecting tech stack/conventions, and removing global duplicates
+
+## [2.8.1] - 2026-02-10
+
+### Added
+- Workflow Preferences section in global and project CLAUDE.md templates (Research Policy, Phase Flow defaults with per-project override support)
+
+## [2.8.0] - 2026-02-10
+
+### Added
+- Backlog management system: 7 new commands (`backlog-add`, `backlog-list`, `backlog-move`, `backlog-edit`, `backlog-remove`, `backlog-promote`, `backlog-settings`)
+- 2 new templates (`backlog.md`, `backlog-settings.md`)
+- Backlog initialization in `gsd-t-init` with auto-category derivation
+- Backlog summary in `gsd-t-status` report
+- Backlog section in `gsd-t-help`
+
+### Changed
+- Updated `gsd-t-init`, `gsd-t-status`, `gsd-t-help`, CLAUDE-global template, README with backlog integration
+
+## [2.7.0] - 2026-02-09
+
+### Added
+- `update-all` CLI command — updates global install + all registered project CLAUDE.md files
+- `register` CLI command — manually register a project in the GSD-T project registry
+- Auto-registration on `gsd-t init`
+- Project registry at `~/.claude/.gsd-t-projects`
+
+## [2.6.0] - 2026-02-09
+
+### Added
+- Destructive Action Guard — mandatory safeguard requiring explicit user approval before destructive or structural changes (schema drops, architecture replacements, module removal)
+- Guard enforced in global CLAUDE.md, project template, and all execution commands
+
+## [2.5.0] - 2026-02-09
+
+### Changed
+- Audited all 27 command files — added Document Ripple and Test Verification steps to 15 commands that were missing them
+- All code-modifying commands now enforce doc updates and test runs before completion
+
+## [2.4.0] - 2026-02-09
+
+### Added
+- Automatic version bumping in `checkin` command — determines patch/minor/major from change type
+
+## [2.3.0] - 2026-02-09
+
+### Added
+- Branch Guard — prevents commits on wrong branch by checking `Expected branch` in CLAUDE.md
+
+## [2.2.1] - 2026-02-09
+
+### Fixed
+- `gsd-t-discuss` now stops for user review when manually invoked (was auto-continuing even in manual mode)
+
+## [2.2.0] - 2026-02-09
+
+### Added
+- E2E test support in `test-sync`, `verify`, and `execute` commands
+
+## [2.1.0] - 2026-02-09
+
+### Added
+- `gsd-t-populate` command — auto-populate living docs from existing codebase
+- Semantic versioning system tracked in `progress.md`
+- Auto-update README on version changes
+
+## [2.0.2] - 2026-02-07
+
+### Changed
+- `gsd-t-init` now creates all 4 living document templates (`requirements.md`, `architecture.md`, `workflows.md`, `infrastructure.md`)
+- `gsd-t-scan` cross-populates findings into living docs
+
+## [2.0.1] - 2026-02-07
+
+### Fixed
+- Added `gsd-t-brainstorm` to all 4 reference files (README, GSD-T-README, CLAUDE-global, gsd-t-help)
+- Fixed workflow diagram alignment
+
+## [2.0.0] - 2026-02-07
+
+### Added
+- Renamed package to `@tekyzinc/gsd-t`
+- `gsd-t-brainstorm` command — creative exploration, rethinking, and idea generation
+- Initialized GSD-T state (`.gsd-t/` directory) on itself
+
+### Changed
+- Complete framework rewrite from GSD to GSD-T (contract-driven development)
+- npm package with CLI installer (`bin/gsd-t.js`)
+- 6 CLI subcommands: install, update, init, status, doctor, uninstall
+
+## [1.0.0] - 2026-02-07
+
+### Added
+- Initial GSD-T framework implementation
+- Full milestone workflow: partition, discuss, plan, impact, execute, test-sync, integrate, verify, complete
+- Agent Teams support for parallel execution
+- Living documents system (requirements, architecture, workflows, infrastructure)

package/README.md

@@ -18,7 +18,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 31 GSD-T commands + 3 utility commands to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
+This installs 32 GSD-T commands + 3 utility commands to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
 
 ### Start Using It
 
@@ -72,6 +72,7 @@ npx @tekyzinc/gsd-t init [name]    # Scaffold GSD-T project (auto-registers)
 npx @tekyzinc/gsd-t register       # Register current directory as a GSD-T project
 npx @tekyzinc/gsd-t status         # Check installation + version
 npx @tekyzinc/gsd-t doctor         # Diagnose common issues
+npx @tekyzinc/gsd-t changelog      # Open changelog in the browser
 npx @tekyzinc/gsd-t uninstall      # Remove commands (keeps project files)
 ```
 
@@ -101,6 +102,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 
 | Command | Purpose |
 |---------|---------|
+| `/user:gsd-t-setup` | Generate or restructure project CLAUDE.md |
 | `/user:gsd-t-init` | Initialize GSD-T structure in project |
 | `/user:gsd-t-project` | Full project → milestone roadmap |
 | `/user:gsd-t-feature` | Major feature → impact analysis + milestones |
@@ -268,8 +270,8 @@ get-stuff-done-teams/
 ├── LICENSE
 ├── bin/
 │   └── gsd-t.js                       # CLI installer
-├── commands/                          # 34 slash commands
-│   ├── gsd-t-*.md                     # 31 GSD-T workflow commands
+├── commands/                          # 35 slash commands
+│   ├── gsd-t-*.md                     # 32 GSD-T workflow commands
 │   ├── branch.md                      # Git branch helper
 │   ├── checkin.md                     # Auto-version + commit/push helper
 │   └── Claude-md.md                   # Reload CLAUDE.md directives

package/bin/gsd-t.js

@@ -12,11 +12,13 @@
  *   npx @tekyzinc/gsd-t status      — Show what's installed and check for updates
  *   npx @tekyzinc/gsd-t uninstall   — Remove GSD-T commands (leaves project files alone)
  *   npx @tekyzinc/gsd-t doctor      — Diagnose common issues
+ *   npx @tekyzinc/gsd-t changelog   — Open changelog in the browser
  */
 
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const { execSync } = require("child_process");
 
 // ─── Configuration ───────────────────────────────────────────────────────────
 
@@ -35,6 +37,7 @@ const PKG_EXAMPLES = path.join(PKG_ROOT, "examples");
 
 // Read our version from package.json
 const PKG_VERSION = require(path.join(PKG_ROOT, "package.json")).version;
+const CHANGELOG_URL = "https://github.com/Tekyz-Inc/get-stuff-done-teams/blob/main/CHANGELOG.md";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -64,6 +67,12 @@ function info(msg) {
 function heading(msg) {
   console.log(`\n${BOLD}${msg}${RESET}`);
 }
+function link(text, url) {
+  return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+function versionLink(ver) {
+  return link(`v${ver || PKG_VERSION}`, CHANGELOG_URL);
+}
 
 function ensureDir(dir) {
   if (!fs.existsSync(dir)) {
@@ -140,7 +149,7 @@ function doInstall(opts = {}) {
   const isUpdate = opts.update || false;
   const verb = isUpdate ? "Updating" : "Installing";
 
-  heading(`${verb} GSD-T v${PKG_VERSION}`);
+  heading(`${verb} GSD-T ${versionLink()}`);
   log("");
 
   // 1. Create ~/.claude/commands/ if needed
@@ -224,7 +233,7 @@ function doInstall(opts = {}) {
   log("");
   log(`  Commands: ${gsdtCommands.length} GSD-T + ${utilityCommands.length} utility commands in ~/.claude/commands/`);
   log(`  Config:   ~/.claude/CLAUDE.md`);
-  log(`  Version:  ${PKG_VERSION}`);
+  log(`  Version:  ${versionLink()}`);
   log("");
   log(`${BOLD}Quick Start:${RESET}`);
   log(`  ${DIM}$${RESET} cd your-project`);
@@ -245,7 +254,7 @@ function doUpdate() {
   const installedVersion = getInstalledVersion();
 
   if (installedVersion === PKG_VERSION) {
-    heading(`GSD-T v${PKG_VERSION}`);
+    heading(`GSD-T ${versionLink()}`);
     info("Already up to date!");
     log("");
     log("  To force a reinstall, run:");
@@ -255,7 +264,7 @@ function doUpdate() {
   }
 
   if (installedVersion) {
-    heading(`Updating GSD-T: v${installedVersion} → v${PKG_VERSION}`);
+    heading(`Updating GSD-T: ${versionLink(installedVersion)} → ${versionLink()}`);
   }
 
   doInstall({ update: true });
@@ -372,12 +381,12 @@ function doStatus() {
   // Installed version
   const installedVersion = getInstalledVersion();
   if (installedVersion) {
-    success(`Installed version: ${installedVersion}`);
+    success(`Installed version: ${versionLink(installedVersion)}`);
     if (installedVersion !== PKG_VERSION) {
-      warn(`Latest version: ${PKG_VERSION}`);
+      warn(`Latest version: ${versionLink()}`);
       info(`Run 'npx @tekyzinc/gsd-t update' to update`);
     } else {
-      success(`Up to date (latest: ${PKG_VERSION})`);
+      success(`Up to date (latest: ${versionLink()})`);
     }
   } else {
     error("GSD-T not installed");
@@ -502,7 +511,7 @@ function doUpdateAll() {
   if (installedVersion !== PKG_VERSION) {
     doInstall({ update: true });
   } else {
-    heading(`GSD-T v${PKG_VERSION}`);
+    heading(`GSD-T ${versionLink()}`);
     success("Global commands already up to date");
   }
 
@@ -531,6 +540,7 @@ function doUpdateAll() {
   for (const projectDir of projects) {
     const projectName = path.basename(projectDir);
     const claudeMd = path.join(projectDir, "CLAUDE.md");
+    let projectUpdated = false;
 
     // Check project still exists
     if (!fs.existsSync(projectDir)) {
@@ -548,56 +558,77 @@ function doUpdateAll() {
     const content = fs.readFileSync(claudeMd, "utf8");
 
     // Check if the project CLAUDE.md needs the Destructive Action Guard
-    if (content.includes("Destructive Action Guard")) {
-      info(`${projectName} — already up to date`);
-      skipped++;
-      continue;
+    if (!content.includes("Destructive Action Guard")) {
+      const guardSection = [
+        "",
+        "",
+        "# Destructive Action Guard (MANDATORY)",
+        "",
+        "**NEVER perform destructive or structural changes without explicit user approval.** This applies at ALL autonomy levels.",
+        "",
+        "Before any of these actions, STOP and ask the user:",
+        "- DROP TABLE, DROP COLUMN, DROP INDEX, TRUNCATE, DELETE without WHERE",
+        "- Renaming or removing database tables or columns",
+        "- Schema migrations that lose data or break existing queries",
+        "- Replacing an existing architecture pattern (e.g., normalized → denormalized)",
+        "- Removing or replacing existing files/modules that contain working functionality",
+        "- Changing ORM models in ways that conflict with the existing database schema",
+        "- Removing API endpoints or changing response shapes that existing clients depend on",
+        "- Any change that would require other parts of the system to be rewritten",
+        "",
+        '**Rule: "Adapt new code to existing structures, not the other way around."**',
+        "",
+      ].join("\n");
+
+      let newContent;
+      const preCommitMatch = content.match(/\n(#{1,3} Pre-Commit Gate)/);
+      const dontDoMatch = content.match(/\n(#{1,3} Don't Do These Things)/);
+
+      if (preCommitMatch) {
+        newContent = content.replace(
+          "\n" + preCommitMatch[1],
+          guardSection + "\n" + preCommitMatch[1]
+        );
+      } else if (dontDoMatch) {
+        newContent = content.replace(
+          "\n" + dontDoMatch[1],
+          guardSection + "\n" + dontDoMatch[1]
+        );
+      } else {
+        newContent = content + guardSection;
+      }
+
+      fs.writeFileSync(claudeMd, newContent);
+      success(`${projectName} — added Destructive Action Guard`);
+      projectUpdated = true;
     }
 
-    // Add the Destructive Action Guard section
-    const guardSection = [
-      "",
-      "",
-      "# Destructive Action Guard (MANDATORY)",
-      "",
-      "**NEVER perform destructive or structural changes without explicit user approval.** This applies at ALL autonomy levels.",
-      "",
-      "Before any of these actions, STOP and ask the user:",
-      "- DROP TABLE, DROP COLUMN, DROP INDEX, TRUNCATE, DELETE without WHERE",
-      "- Renaming or removing database tables or columns",
-      "- Schema migrations that lose data or break existing queries",
-      "- Replacing an existing architecture pattern (e.g., normalized → denormalized)",
-      "- Removing or replacing existing files/modules that contain working functionality",
-      "- Changing ORM models in ways that conflict with the existing database schema",
-      "- Removing API endpoints or changing response shapes that existing clients depend on",
-      "- Any change that would require other parts of the system to be rewritten",
-      "",
-      '**Rule: "Adapt new code to existing structures, not the other way around."**',
-      "",
-    ].join("\n");
-
-    let newContent;
-    // Match headings at any level (# or ## or ###)
-    const preCommitMatch = content.match(/\n(#{1,3} Pre-Commit Gate)/);
-    const dontDoMatch = content.match(/\n(#{1,3} Don't Do These Things)/);
-
-    if (preCommitMatch) {
-      newContent = content.replace(
-        "\n" + preCommitMatch[1],
-        guardSection + "\n" + preCommitMatch[1]
-      );
-    } else if (dontDoMatch) {
-      newContent = content.replace(
-        "\n" + dontDoMatch[1],
-        guardSection + "\n" + dontDoMatch[1]
-      );
-    } else {
-      newContent = content + guardSection;
+    // Create CHANGELOG.md if it doesn't exist
+    const changelogPath = path.join(projectDir, "CHANGELOG.md");
+    if (!fs.existsSync(changelogPath)) {
+      const today = new Date().toISOString().split("T")[0];
+      const changelogContent = [
+        "# Changelog",
+        "",
+        "All notable changes to this project are documented here.",
+        "",
+        `## [0.1.0] - ${today}`,
+        "",
+        "### Added",
+        "- Initial changelog created by GSD-T",
+        "",
+      ].join("\n");
+      fs.writeFileSync(changelogPath, changelogContent);
+      success(`${projectName} — created CHANGELOG.md`);
+      projectUpdated = true;
     }
 
-    fs.writeFileSync(claudeMd, newContent);
-    success(`${projectName} — updated CLAUDE.md`);
-    updated++;
+    if (projectUpdated) {
+      updated++;
+    } else {
+      info(`${projectName} — already up to date`);
+      skipped++;
+    }
   }
 
   // Summary
@@ -628,7 +659,6 @@ function doDoctor() {
   }
 
   // 2. Claude Code installed?
-  const { execSync } = require("child_process");
   try {
     const claudeVersion = execSync("claude --version 2>&1", { encoding: "utf8" }).trim();
     success(`Claude Code: ${claudeVersion}`);
@@ -746,6 +776,19 @@ function doRegister() {
   log("");
 }
 
+function doChangelog() {
+  const openCmd =
+    process.platform === "win32" ? "start" :
+    process.platform === "darwin" ? "open" : "xdg-open";
+  try {
+    execSync(`${openCmd} ${CHANGELOG_URL}`, { stdio: "ignore" });
+    success(`Opened changelog in browser`);
+  } catch {
+    // Fallback: print the URL
+    log(`\n  ${CHANGELOG_URL}\n`);
+  }
+}
+
 function showHelp() {
   log("");
   log(`${BOLD}GSD-T${RESET} — Contract-Driven Development for Claude Code`);
@@ -762,6 +805,7 @@ function showHelp() {
   log(`  ${CYAN}status${RESET}         Show installation status + check for updates`);
   log(`  ${CYAN}uninstall${RESET}      Remove GSD-T commands (keeps project files)`);
   log(`  ${CYAN}doctor${RESET}         Diagnose common issues`);
+  log(`  ${CYAN}changelog${RESET}      Open changelog in the browser`);
   log(`  ${CYAN}help${RESET}           Show this help`);
   log("");
   log(`${BOLD}Examples:${RESET}`);
@@ -807,6 +851,9 @@ switch (command) {
   case "doctor":
     doDoctor();
     break;
+  case "changelog":
+    doChangelog();
+    break;
   case "help":
   case "--help":
   case "-h":

package/commands/checkin.md

@@ -20,11 +20,18 @@ Automatically stage, commit, and push all updated files to GitHub with automatic
 8. Update the version in `package.json`
 9. If `.gsd-t/progress.md` exists, check for a `## Version` line and update it (or add one after the `## Date` line)
 
+### Release Notes
+
+10. If `CHANGELOG.md` exists in the project root, prepend an entry for this version:
+    - Use the format: `## [X.Y.Z] - YYYY-MM-DD` followed by `### Added`, `### Changed`, `### Fixed`, or `### Removed` subsections as appropriate
+    - Summarize the changes in 1-3 bullet points per subsection
+    - Place the new entry directly after the file header (before any existing version entries)
+
 ### Commit and Push
 
-10. Stage all changes (including the version bump) with `git add -A`
-11. Create a commit with a descriptive message summarizing the changes. Include `(vX.Y.Z)` at the end of the first line. Example: `fix: resolve branch guard edge case (v2.3.1)`
-12. Push to origin with `git push`
-13. Confirm success to the user, including the old → new version
+11. Stage all changes (including the version bump and changelog) with `git add -A`
+12. Create a commit with a descriptive message summarizing the changes. Include `(vX.Y.Z)` at the end of the first line. Example: `fix: resolve branch guard edge case (v2.3.1)`
+13. Push to origin with `git push`
+14. Confirm success to the user, including the old → new version
 
 Use the standard commit message format with Co-Authored-By line.

package/commands/gsd-t-help.md

@@ -15,6 +15,7 @@ GETTING STARTED
 ───────────────────────────────────────────────────────────────────────────────
   prompt              Help formulate your idea before committing to a command
   brainstorm          Creative exploration, rethinking, and idea generation
+  setup               Generate or restructure project CLAUDE.md
   init                Initialize GSD-T structure in current project
   project             New project → requirements → milestone roadmap
   feature             Major feature → impact analysis → milestones
@@ -131,6 +132,12 @@ Use these when user asks for help on a specific command:
 - **Use when**: You want to explore ideas, challenge assumptions, or break out of tunnel vision
 - **Modes**: Ideation, Enhancement, Rethink, Unstuck, Blue Sky
 
+### setup
+- **Summary**: Generate or restructure the project-level CLAUDE.md
+- **Auto-invoked**: No
+- **Creates/Updates**: `CLAUDE.md`
+- **Use when**: Starting a new project, migrating from GSD, or restructuring an existing CLAUDE.md to complement the global one
+
 ### init
 - **Summary**: Initialize GSD-T directory structure in current project
 - **Auto-invoked**: No

package/commands/gsd-t-setup.md

@@ -0,0 +1,213 @@
+# GSD-T: Setup — Generate or Restructure Project CLAUDE.md
+
+You are generating or restructuring the project-level CLAUDE.md for the current project. The goal is a well-structured file that complements the global `~/.claude/CLAUDE.md` without duplicating it.
+
+## Step 1: Read Global Context
+
+Read `~/.claude/CLAUDE.md` to understand what's already covered globally:
+- Prime Directives
+- GSD-T workflow, commands, living documents
+- Versioning, Destructive Action Guard, Pre-Commit Gate
+- Autonomous Execution Rules, Workflow Preferences defaults
+- Code Standards defaults
+
+**Rule**: Anything in the global file should NOT be repeated in the project file. The project file only contains project-specific information and overrides.
+
+## Step 2: Scan the Project
+
+Gather as much as possible automatically:
+
+### 2a: Project Identity
+- Project name from `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, repo name, or directory name
+- Description from package manifest or README
+
+### 2b: Tech Stack Detection
+Scan for and identify:
+- **Language**: from file extensions, configs (`tsconfig.json`, `pyproject.toml`, `go.mod`, etc.)
+- **Framework**: from dependencies (`package.json`, `requirements.txt`, `Pipfile`, etc.)
+- **Database**: from dependencies, config files, docker-compose, `.env` vars
+- **Frontend**: from dependencies, directory structure (`client/`, `src/components/`)
+- **Testing**: from test configs (`vitest.config`, `pytest.ini`, `jest.config`, etc.)
+- **Deployment**: from `Dockerfile`, CI/CD configs, cloud configs
+
+### 2c: Project Structure
+- Scan directories to build "Where Things Live" table
+- Identify key entry points, config files, and module boundaries
+
+### 2d: Existing Conventions
+- **Naming**: Sample 5-10 files and functions to detect naming patterns (snake_case, camelCase, kebab-case, PascalCase)
+- **File organization**: Flat, feature-based, layer-based?
+- **Import style**: Absolute, relative, aliases?
+
+### 2e: Existing Documentation
+- Check for `docs/` directory and which living documents exist
+- Check for `.gsd-t/` directory (already initialized?)
+- Check for `.env.example` or environment docs
+
+### 2f: Git State
+- Current branch (for Branch Guard)
+- Remote URL (for reference)
+
+## Step 3: Check Existing CLAUDE.md
+
+### If CLAUDE.md exists:
+
+Read it and categorize every section:
+
+1. **Project-specific (KEEP)**: Overview, Tech Stack, Branch Guard, Where Things Live, Conventions, Testing, Environment Variables, Deployed URLs, Reference Projects, project-specific "Don't Do" rules
+2. **Global duplicate (REMOVE)**: Anything that duplicates the global CLAUDE.md — Prime Directives, GSD-T workflow descriptions, Destructive Action Guard (unless project-specific additions), Pre-Commit Gate, Autonomous Execution Rules
+3. **GSD/legacy sections (MIGRATE)**: `## GSD Workflow Preferences` or similar → extract project-specific preferences into `## Workflow Preferences` using the new format
+4. **Stale content (FLAG)**: Sections that reference outdated tech, removed features, or incorrect paths
+
+Present findings to user:
+```
+CLAUDE.md Analysis:
+  KEEP:    {N} project-specific sections
+  REMOVE:  {N} sections that duplicate global CLAUDE.md
+  MIGRATE: {N} GSD sections → Workflow Preferences format
+  FLAG:    {N} potentially stale sections
+```
+
+### If no CLAUDE.md exists:
+
+Note: "No existing CLAUDE.md — will generate from scratch."
+
+## Step 4: Ask Targeted Questions
+
+Only ask what could NOT be auto-detected. Skip questions where the answer is already clear from scanning.
+
+**Potential questions** (ask only if not auto-detected):
+
+1. **Branch Guard**: "Which branch should commits target?" (skip if only `main` or `master` exists)
+2. **Autonomy Level**: "What autonomy level? Level 1 (Supervised), Level 2 (Standard — default), Level 3 (Full Auto)" (skip if existing CLAUDE.md already declares it)
+3. **Workflow Preferences**: "Any overrides to the global defaults? (Research Policy, Phase Flow)" (skip if user has no overrides)
+4. **Deployed URLs**: "Production, staging, and local URLs?" (skip if found in .env or existing docs)
+5. **Project-specific rules**: "Any 'never do' rules specific to this project?" (skip if existing CLAUDE.md already has them)
+
+**Do NOT ask about**:
+- Tech stack (auto-detected)
+- Naming conventions (auto-detected)
+- Testing framework (auto-detected)
+- File structure (auto-detected)
+- Anything already covered by the global CLAUDE.md
+
+## Step 5: Generate CLAUDE.md
+
+Build the file using this structure. Include only sections that have real content — omit empty sections entirely.
+
+```markdown
+# {Project Name}
+
+## Branch Guard
+**Expected branch**: {branch}
+
+## Project Overview
+{Brief description — what problem does this solve and for whom?}
+
+### Architecture
+{High-level architecture summary if the project has one — e.g., "Three-tier WebSocket bridge" with a diagram. Keep it concise. Details belong in docs/architecture.md}
+
+## Where Things Live
+
+| Need to find... | Look here |
+|-----------------|-----------|
+| {component} | {path} |
+
+## Key Technologies
+{Bulleted list of language, framework, database, testing, etc.}
+
+## Documentation
+- Requirements: docs/requirements.md
+- Architecture: docs/architecture.md
+- Workflows: docs/workflows.md
+- Infrastructure: docs/infrastructure.md
+
+## Autonomy Level
+**Level {N} — {Name}** (pause at {description})
+
+## Workflow Preferences
+<!-- Override global defaults. Delete what you don't need to override. -->
+
+### Research Policy
+{project-specific overrides, or omit section}
+
+### Phase Flow
+{project-specific overrides, or omit section}
+
+## Testing
+{Framework, file organization, naming, running instructions}
+
+## Code Patterns to Follow
+{Project-specific conventions that differ from or extend global defaults}
+
+### Naming Conventions
+{If different from global defaults}
+
+## Running the App
+{Dev server, build commands, first-time setup}
+
+## Environment Variables
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| {VAR} | {purpose} | {default} |
+
+## Deployed URLs
+- **Production**: {url}
+- **Staging**: {url}
+- **Local**: http://localhost:{port}
+
+## Don't Do These Things
+{Project-specific rules only — don't repeat global rules}
+
+## GSD-T Workflow
+This project uses contract-driven development.
+- State: .gsd-t/progress.md
+- Contracts: .gsd-t/contracts/
+- Domains: .gsd-t/domains/
+
+## Current Status
+See `.gsd-t/progress.md` for current milestone/phase state.
+```
+
+### Section Rules:
+- **NEVER duplicate** global CLAUDE.md content (Destructive Action Guard, Pre-Commit Gate, Prime Directives, etc.)
+- **ALWAYS include**: Branch Guard, GSD-T Workflow, Current Status
+- **Include if relevant**: Where Things Live, Testing, Code Patterns, Environment Variables
+- **Omit if empty**: Deployed URLs (if not deployed), Architecture (if trivial), Workflow Preferences (if no overrides)
+
+## Step 6: Present and Confirm
+
+Show the generated CLAUDE.md content to the user with a summary:
+
+```
+Generated CLAUDE.md for {Project Name}:
+  Sections: {N} ({list of section names})
+  Auto-detected: {tech stack, conventions, structure}
+  From existing: {N} sections preserved
+  Removed: {N} global duplicates
+
+{Show the full generated content}
+
+Write this as CLAUDE.md? (This will replace the existing file if one exists.)
+```
+
+Wait for user confirmation before writing.
+
+## Step 7: Write and Verify
+
+1. Write the CLAUDE.md file
+2. Verify it's valid markdown (no broken tables, unclosed code blocks)
+3. If `.gsd-t/progress.md` exists, log the setup in the Decision Log
+
+## Document Ripple
+
+### Always update:
+1. **`.gsd-t/progress.md`** — Log "Project CLAUDE.md generated/restructured via gsd-t-setup" in Decision Log (if .gsd-t/ exists)
+
+### Skip: No other files are affected by CLAUDE.md generation.
+
+## Test Verification
+
+No tests to run — this command produces a configuration file, not code.
+
+$ARGUMENTS

package/docs/GSD-T-README.md

@@ -71,6 +71,7 @@ GSD-T reads all state files and tells you exactly where you left off.
 
 | Command | Purpose |
 |---------|---------|
+| `/user:gsd-t-setup` | Generate or restructure project CLAUDE.md |
 | `/user:gsd-t-init` | Initialize GSD-T structure in project |
 | `/user:gsd-t-project` | Full project → milestone roadmap |
 | `/user:gsd-t-feature` | Major feature → impact analysis + milestones |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.8.1",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 34 slash commands with backlog management, impact analysis, test sync, and milestone archival",
+  "version": "2.10.0",
+  "description": "GSD-T: Contract-Driven Development for Claude Code — 35 slash commands with backlog management, impact analysis, test sync, and milestone archival",
   "author": "Tekyz, Inc.",
   "license": "MIT",
   "repository": {
@@ -25,7 +25,8 @@
     "commands/",
     "templates/",
     "examples/",
-    "docs/"
+    "docs/",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=16.0.0"

package/templates/CLAUDE-global.md

@@ -34,6 +34,7 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-feature` | Major feature → impact analysis + milestones |
 | `/user:gsd-t-scan` | Deep codebase analysis → techdebt.md |
 | `/user:gsd-t-promote-debt` | Convert debt items to milestones |
+| `/user:gsd-t-setup` | Generate or restructure project CLAUDE.md |
 | `/user:gsd-t-init` | Initialize project structure |
 | `/user:gsd-t-milestone` | Define new milestone |
 | `/user:gsd-t-partition` | Decompose into domains + contracts |