@tekyzinc/gsd-t 2.8.0 → 2.9.0

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
 
@@ -101,6 +101,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 +269,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/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-init.md

@@ -102,6 +102,9 @@ Create a starter template:
 ## Conventions
 - {Coding style, naming patterns — fill this in}
 
+## Workflow Preferences
+<!-- Override global defaults. Delete what you don't need to override. -->
+
 ## GSD-T Workflow
 This project uses contract-driven development.
 - State: .gsd-t/progress.md

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.0",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 34 slash commands with backlog management, impact analysis, test sync, and milestone archival",
+  "version": "2.9.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": {

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 |
@@ -217,6 +218,31 @@ Projects can specify an autonomy level in their project CLAUDE.md:
 
 If not specified, use Level 2.
 
+## Workflow Preferences (Defaults — override in project CLAUDE.md)
+
+### Research Policy
+Before planning a phase, evaluate whether research is needed:
+
+**Run research when:**
+- Phase involves unfamiliar libraries, APIs, or services
+- Architectural decisions are required
+- Integrating external systems
+- Phase scope is ambiguous or complex
+
+**Skip research when:**
+- Patterns are already established from earlier phases
+- Straightforward CRUD, UI, or config work
+- Domain is well understood
+- Phase builds directly on existing code patterns
+
+If in doubt, skip research and proceed — research if execution reveals gaps.
+
+### Phase Flow
+- Upon completing a phase, automatically proceed to the next phase
+- ONLY run Discussion phase if truly required (clear path → skip to Plan)
+- ALWAYS self-verify work by running verification commands
+- NEVER pause to show verification steps — execute them
+
 
 # Don't Do These Things
 

package/templates/CLAUDE-project.md

@@ -36,6 +36,20 @@ This project uses contract-driven development.
 - Contracts: .gsd-t/contracts/
 - Domains: .gsd-t/domains/
 
+## Workflow Preferences
+<!-- Override global defaults from ~/.claude/CLAUDE.md -->
+<!-- Delete lines you don't need to override — globals apply automatically -->
+
+### Research Policy
+<!-- Example overrides: -->
+<!-- "Always research — this project uses cutting-edge APIs" -->
+<!-- "Skip research — well-understood CRUD app" -->
+
+### Phase Flow
+<!-- Example overrides: -->
+<!-- "ALWAYS run Discussion — architecture decisions are critical" -->
+<!-- "Skip discuss unless truly required" -->
+
 ## Project-Specific Conventions
 <!-- Add conventions that override or extend the global CLAUDE.md -->