@tekyzinc/gsd-t 2.0.1 → 2.1.0

package/README.md

@@ -17,7 +17,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 23 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 24 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
 
@@ -103,6 +103,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-feature` | Major feature → impact analysis + milestones |
 | `/user:gsd-t-scan` | Deep codebase analysis → techdebt.md |
 | `/user:gsd-t-promote-debt` | Convert techdebt items to milestones |
+| `/user:gsd-t-populate` | Auto-populate docs from existing codebase |
 
 ### Milestone Workflow
 
@@ -172,9 +173,10 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 your-project/
 ├── CLAUDE.md
 ├── docs/
-│   ├── requirements.md
-│   ├── architecture.md
-│   └── ...
+│   ├── requirements.md                # Functional + technical requirements
+│   ├── architecture.md                # System design, components, data flow
+│   ├── workflows.md                   # User journeys, technical processes
+│   └── infrastructure.md             # Dev setup, DB, cloud, deployment
 ├── .gsd-t/
 │   ├── progress.md                    # Master state file
 │   ├── roadmap.md                     # Milestone roadmap
@@ -249,8 +251,8 @@ get-stuff-done-teams/
 ├── LICENSE
 ├── bin/
 │   └── gsd-t.js                       # CLI installer
-├── commands/                          # 25 slash commands
-│   ├── gsd-t-*.md                     # 22 GSD-T workflow commands
+├── commands/                          # 27 slash commands
+│   ├── gsd-t-*.md                     # 24 GSD-T workflow commands
 │   ├── branch.md                      # Git branch helper
 │   ├── checkin.md                     # Git commit/push helper
 │   └── Claude-md.md                   # Reload CLAUDE.md directives
@@ -266,8 +268,8 @@ get-stuff-done-teams/
 │   ├── settings.json
 │   └── .gsd-t/
 ├── docs/
+│   ├── GSD-T-README.md                # Detailed methodology + usage guide
 │   └── methodology.md
-└── GSD-T-README.md
 ```
 
 ---

package/commands/gsd-t-complete-milestone.md

@@ -84,7 +84,26 @@ Create `summary.md`:
 {Summary of files created/modified/deleted}
 ```
 
-## Step 5: Clean Working State
+## Step 5: Bump Version
+
+GSD-T tracks project version in `.gsd-t/progress.md` using semantic versioning: `Major.Minor.Patch`
+
+- **Major** (X.0.0): Breaking changes, major rework, v1 launch
+- **Minor** (0.X.0): New features, completed feature milestones
+- **Patch** (0.0.X): Bug fixes, minor improvements, cleanup milestones
+
+Determine the version bump based on the milestone:
+1. Read current version from `.gsd-t/progress.md`
+2. Assess milestone scope:
+   - Was this a major/breaking milestone? → bump **major**, reset minor and patch to 0
+   - Was this a feature milestone? → bump **minor**, reset patch to 0
+   - Was this a bugfix/cleanup/debt milestone? → bump **patch**
+3. Update version in `.gsd-t/progress.md`
+4. If a package manifest exists (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.), update its version to match
+5. Update `README.md` version badge or version reference if present
+6. Include version in the milestone summary and git tag
+
+## Step 6: Clean Working State
 
 Reset `.gsd-t/` for next milestone:
 
@@ -97,30 +116,42 @@ Reset `.gsd-t/` for next milestone:
 ```markdown
 # GSD-T Progress
 
+## Version: {new version}
 ## Current Milestone
 None — ready for next milestone
 
 ## Completed Milestones
-| Milestone | Completed | Tag |
-|-----------|-----------|-----|
-| {name} | {date} | {tag} |
-| {previous} | {date} | {tag} |
+| Milestone | Version | Completed | Tag |
+|-----------|---------|-----------|-----|
+| {name} | {version} | {date} | v{version} |
+| {previous} | {version} | {date} | v{version} |
 
 ## Decision Log
 {Keep the decision log — it's valuable context}
 ```
 
-## Step 6: Create Git Tag
+## Step 7: Update README.md
+
+If `README.md` exists, update it to reflect the completed milestone:
+- Add or update a **Features** / **What's Included** section with capabilities delivered
+- Update version number if displayed in README
+- Update setup instructions if infrastructure changed
+- Update tech stack if new dependencies were added
+- Keep existing user content — merge, don't overwrite
+
+If `README.md` doesn't exist, create one with project name, description, version, tech stack, setup instructions, and link to `docs/`.
+
+## Step 8: Create Git Tag
 
 ```bash
 # Stage any remaining .gsd-t changes
 git add .gsd-t/
 
 # Commit the archive
-git commit -m "milestone({milestone-name}): complete and archive"
+git commit -m "milestone({milestone-name}): complete and archive v{version}"
 
-# Create annotated tag
-git tag -a "milestone/{milestone-name}" -m "Milestone: {name}
+# Create annotated tag with version
+git tag -a "v{version}" -m "v{version} — Milestone: {name}
 
 {Brief description from summary}
 
@@ -128,27 +159,28 @@ Domains: {list}
 Verified: {date}"
 ```
 
-## Step 7: Report Completion
+## Step 9: Report Completion
 
 ```
-✅ Milestone "{name}" completed!
+✅ Milestone "{name}" completed — v{version}
 
 📁 Archived to: .gsd-t/milestones/{name}-{date}/
-🏷️  Tagged as: milestone/{name}
+🏷️  Tagged as: v{version}
 
 Summary:
+- Version: {previous version} → {new version}
 - Domains completed: {N}
 - Tasks completed: {N}
 - Contracts: {N} defined/updated
 - Tests: {N} added/updated
 
 Next steps:
-- Push tags: git push origin milestone/{name}
+- Push tags: git push origin v{version}
 - Start next milestone: /user:gsd-t-milestone "{next name}"
 - Or view roadmap: /user:gsd-t-status
 ```
 
-## Step 8: Update Roadmap (if exists)
+## Step 10: Update Roadmap (if exists)
 
 If `.gsd-t/roadmap.md` exists:
 - Mark this milestone as complete

package/commands/gsd-t-help.md

@@ -44,6 +44,7 @@ UTILITIES
   quick               Fast task with GSD-T guarantees
   debug               Systematic debugging with state
   promote-debt        Convert techdebt items to milestones
+  populate            Auto-populate docs from existing codebase
 
 ───────────────────────────────────────────────────────────────────────────────
 Type /user:gsd-t-help {command} for detailed help on any command.
@@ -240,6 +241,12 @@ Use these when user asks for help on a specific command:
 - **Updates**: `.gsd-t/roadmap.md`, `.gsd-t/techdebt.md`
 - **Use when**: Ready to address technical debt items
 
+### populate
+- **Summary**: Auto-populate all living docs from existing codebase analysis
+- **Auto-invoked**: No
+- **Updates**: `docs/requirements.md`, `docs/architecture.md`, `docs/workflows.md`, `docs/infrastructure.md`, `.gsd-t/progress.md`
+- **Use when**: You have an existing codebase and want to fill docs with real findings instead of placeholders
+
 ## Unknown Command
 
 If user asks for help on unrecognized command:

package/commands/gsd-t-init.md

@@ -37,6 +37,7 @@ Create `.gsd-t/progress.md`:
 # GSD-T Progress
 
 ## Project: {name from CLAUDE.md or $ARGUMENTS}
+## Version: 0.1.0
 ## Status: INITIALIZED
 ## Date: {today}
 
@@ -73,9 +74,10 @@ Create a starter template:
 {Languages, frameworks, services — fill this in}
 
 ## Documentation
-- Requirements: docs/requirements.md (if exists)
-- Architecture: docs/architecture.md (if exists)
-- Schema: docs/schema.md (if exists)
+- Requirements: docs/requirements.md
+- Architecture: docs/architecture.md
+- Workflows: docs/workflows.md
+- Infrastructure: docs/infrastructure.md
 
 ## Conventions
 - {Coding style, naming patterns — fill this in}
@@ -91,14 +93,30 @@ If `CLAUDE.md` exists but doesn't reference GSD-T, append the GSD-T section.
 
 ## Step 5: Create docs/ if Needed
 
-If no `docs/` directory:
+If no `docs/` directory, create it with all 4 living document templates.
+For each file, skip if it already exists:
+
 ```
 docs/
-├── requirements.md    — (create placeholder)
-└── architecture.md    — (create placeholder)
+├── requirements.md    — Functional, technical, and non-functional requirements
+├── architecture.md    — System design, components, data flow, design decisions
+├── workflows.md       — User journeys, technical processes, API flows
+└── infrastructure.md  — Dev setup, DB commands, cloud provisioning, deployment, credentials
 ```
 
-## Step 6: Map Existing Codebase (if code exists)
+These are the living documents that persist across milestones and keep institutional knowledge alive. The `infrastructure.md` is especially important — it captures the exact commands for provisioning cloud resources, setting up databases, managing secrets, and deploying, so this knowledge doesn't get lost between sessions.
+
+## Step 6: Ensure README.md Exists
+
+If no `README.md` exists, create one with:
+- Project name and brief description
+- Tech stack summary
+- Getting started / setup instructions (from existing configs or placeholder)
+- Link to `docs/` for detailed documentation
+
+If `README.md` exists, leave it as-is — don't overwrite user content during init.
+
+## Step 7: Map Existing Codebase (if code exists)
 
 If there's existing source code:
 1. Scan the codebase structure
@@ -107,7 +125,7 @@ If there's existing source code:
 4. Add findings to CLAUDE.md
 5. Log in progress.md: "Existing codebase analyzed — {summary}"
 
-## Step 7: Report
+## Step 8: Report
 
 Tell the user:
 1. What was created

package/commands/gsd-t-scan.md

@@ -310,7 +310,65 @@ Estimated effort: {assessment}
 Can be scheduled: During next maintenance window
 ```
 
-## Step 5: Update Project State
+## Step 5: Update Living Documents
+
+The scan produces deep analysis in `.gsd-t/scan/`. Now cross-populate findings into the living docs so knowledge persists across milestones.
+
+### docs/architecture.md
+Using findings from `.gsd-t/scan/architecture.md`, update or create `docs/architecture.md`:
+- System overview (stack, structure, patterns)
+- Component descriptions with locations and dependencies
+- Data flow (request → handler → service → data layer → response)
+- Data models from schema files or ORM definitions
+- API structure from route definitions
+- External integrations
+- Design decisions found in code comments or configs
+
+If the file exists, merge new findings — don't overwrite existing content.
+
+### docs/workflows.md
+Using findings from `.gsd-t/scan/business-rules.md`, update or create `docs/workflows.md`:
+- User workflows traced from routes/handlers (registration, login, core features)
+- Technical workflows from cron jobs, queue workers, scheduled tasks
+- API workflows for multi-step operations
+- Integration workflows for external system syncing
+- State machines and approval flows discovered in code
+
+### docs/infrastructure.md
+Scan the codebase for operational knowledge and update or create `docs/infrastructure.md`:
+- **Quick Reference commands** from package.json scripts, Makefile, README, CI/CD configs
+- **Local development setup** from README, docker-compose, .env.example
+- **Database commands** from migrations, seeds, ORM config, backup scripts
+- **Cloud provisioning** from Terraform, CloudFormation, Pulumi, or deployment scripts
+- **Credentials and secrets** from .env.example (names only, not values) and secret manager configs
+- **Deployment** from CI/CD configs, Dockerfiles, cloud platform configs
+- **Logging and monitoring** from any logging setup or dashboard configs
+
+This is critical — infrastructure knowledge is the most commonly lost between sessions.
+
+### docs/requirements.md
+Using all scan findings, update or create `docs/requirements.md`:
+- Functional requirements discovered from routes, handlers, UI components
+- Technical requirements from configs, package.json, runtime settings
+- Non-functional requirements from performance configs, rate limits, caching
+
+### README.md
+Update or create `README.md` with scan findings:
+- Project name and description
+- Tech stack and versions discovered
+- Getting started / setup instructions (from infrastructure findings)
+- Brief architecture overview
+- Link to `docs/` for detailed documentation
+
+If `README.md` exists, merge — update tech stack and setup sections but preserve the user's existing structure and custom content.
+
+### For all docs:
+- If the file exists and has real content, **merge** — don't overwrite
+- If the file exists with only placeholder text, **replace** with real findings
+- If the file doesn't exist, **create** it
+- Replace `{Project Name}` and `{Date}` tokens with actual values
+
+## Step 6: Update Project State
 
 If `.gsd-t/progress.md` exists:
 - Log scan in Decision Log
@@ -323,7 +381,7 @@ If `.gsd-t/roadmap.md` exists:
 If `CLAUDE.md` exists:
 - Suggest updates for any patterns or conventions discovered during scan
 
-## Step 6: Report to User
+## Step 7: Report to User
 
 Present a summary:
 1. Architecture overview (brief)

package/docs/GSD-T-README.md

@@ -76,6 +76,7 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-feature` | Major feature → impact analysis + milestones |
 | `/user:gsd-t-scan` | Deep codebase analysis → techdebt.md |
 | `/user:gsd-t-promote-debt` | Convert techdebt items to milestones |
+| `/user:gsd-t-populate` | Auto-populate docs from existing codebase |
 
 ### Milestone Workflow
 
@@ -148,9 +149,10 @@ GSD-T reads all state files and tells you exactly where you left off.
 your-project/
 ├── CLAUDE.md                          # Project conventions + GSD-T reference
 ├── docs/
-│   ├── requirements.md
-│   ├── architecture.md
-│   └── ...
+│   ├── requirements.md                # Functional + technical requirements
+│   ├── architecture.md                # System design, components, data flow
+│   ├── workflows.md                   # User journeys, technical processes
+│   └── infrastructure.md             # Dev setup, DB, cloud, deployment
 ├── .gsd-t/
 │   ├── progress.md                    # Master state file
 │   ├── roadmap.md                     # Milestone roadmap

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 27 slash commands with impact analysis, test sync, and milestone archival",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -49,6 +49,7 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-status` | Cross-domain progress view |
 | `/user:gsd-t-debug` | Systematic debugging |
 | `/user:gsd-t-quick` | Fast task, respects contracts |
+| `/user:gsd-t-populate` | Auto-populate docs from existing codebase |
 | `/user:gsd-t-resume` | Restore context, continue |
 | `/user:branch` | Create and switch to a new git branch |
 | `/user:checkin` | Stage, commit, and push all changes |
@@ -65,7 +66,8 @@ These documents MUST be maintained and referenced throughout development:
 | **Architecture** | `docs/architecture.md` | System design, components, data flow, decisions |
 | **Workflows** | `docs/workflows.md` | User journeys and technical process flows |
 | **Infrastructure** | `docs/infrastructure.md` | Commands, DB setup, server access, creds |
-| **Progress** | `.gsd-t/progress.md` | Current milestone/phase state |
+| **README** | `README.md` | Project overview, setup, features |
+| **Progress** | `.gsd-t/progress.md` | Current milestone/phase state + version |
 | **Contracts** | `.gsd-t/contracts/` | Interfaces between domains |
 | **Tech Debt** | `.gsd-t/techdebt.md` | Debt register from scans |
 
@@ -84,6 +86,21 @@ NEED TO UNDERSTAND SOMETHING?
 ```
 
 
+# Versioning
+
+GSD-T tracks project version in `.gsd-t/progress.md` using semantic versioning: `Major.Minor.Patch`
+
+| Segment | Bumped When | Example |
+|---------|-------------|---------|
+| **Major** | Breaking changes, major rework, v1 launch | 1.0.0 → 2.0.0 |
+| **Minor** | New features, completed feature milestones | 1.1.0 → 1.2.0 |
+| **Patch** | Bug fixes, minor improvements, cleanup | 1.1.1 → 1.1.2 |
+
+- Version is set during `gsd-t-init` (starts at `0.1.0`)
+- Version is bumped during `gsd-t-complete-milestone` based on milestone scope
+- Version is reflected in: `progress.md`, `README.md`, package manifest (if any), and git tags (`v{version}`)
+
+
 # Autonomous Execution Rules
 
 ## Prime Rule

package/templates/progress.md

@@ -1,6 +1,7 @@
 # GSD-T Progress
 
 ## Project: {Project Name}
+## Version: 0.1.0
 ## Status: INITIALIZED
 ## Date: {Date}