@tekyzinc/gsd-t 2.0.2 → 2.2.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-execute.md

@@ -27,10 +27,12 @@ For each task:
 3. Read the domain's constraints.md — follow all patterns
 4. Implement the task
 5. Verify acceptance criteria are met
-6. Run the Pre-Commit Gate checklist from CLAUDE.md — update ALL affected docs BEFORE committing
-7. Commit with a descriptive message: `[{domain}] Task {N}: {description}`
-8. Update `.gsd-t/progress.md` — mark task complete
-9. If you've reached a CHECKPOINT in integration-points.md, pause and verify the contract before continuing
+6. Run affected unit tests — fix any failures before proceeding
+7. If E2E framework exists and task changed UI/routes/flows: run affected E2E specs, update specs if needed
+8. Run the Pre-Commit Gate checklist from CLAUDE.md — update ALL affected docs BEFORE committing
+9. Commit with a descriptive message: `[{domain}] Task {N}: {description}`
+10. Update `.gsd-t/progress.md` — mark task complete
+11. If you've reached a CHECKPOINT in integration-points.md, pause and verify the contract before continuing
 
 ### Team Mode (when agent teams are enabled)
 Spawn teammates for independent domains:

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}
 
@@ -105,7 +106,17 @@ docs/
 
 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: Map Existing Codebase (if code exists)
+## 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
@@ -114,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

@@ -352,6 +352,16 @@ Using all scan findings, update or create `docs/requirements.md`:
 - 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

package/commands/gsd-t-test-sync.md

@@ -15,9 +15,11 @@ Read:
 4. `.gsd-t/domains/{current}/tasks.md` — recent completed tasks
 
 Identify:
-- Test framework (pytest, jest, vitest, etc.)
+- **Unit/integration test framework** (pytest, jest, vitest, etc.)
+- **E2E test framework** (Playwright, Cypress, Puppeteer, etc.) — check for `playwright.config.*`, `cypress.config.*`, `playwright/`, `cypress/`, `e2e/`, or E2E-related dependencies in package.json/requirements.txt
 - Test directory structure
 - Naming conventions
+- Test run commands (from package.json scripts, Makefile, or CI config)
 
 ## Step 2: Map Code to Tests
 
@@ -77,6 +79,7 @@ Tests that sometimes fail:
 
 ## Step 4: Run Affected Tests
 
+### A) Unit/Integration Tests
 Execute tests that cover changed code:
 
 ```bash
@@ -87,7 +90,34 @@ pytest tests/test_{module}.py -v
 npm test -- --testPathPattern="{module}"
 ```
 
-Capture results:
+### B) E2E Tests
+If an E2E framework is detected, run E2E tests affected by the changes:
+
+```bash
+# Playwright
+npx playwright test {affected-spec}.spec.ts
+
+# Cypress
+npx cypress run --spec "cypress/e2e/{affected-spec}.cy.ts"
+```
+
+Determine which E2E specs are affected:
+- Changed a UI component or page? → Run specs that test that page/flow
+- Changed an API endpoint? → Run specs that exercise that endpoint
+- Changed auth/session logic? → Run all auth-related E2E specs
+- Changed database schema? → Run specs that depend on that data
+- Not sure what's affected? → Run the full E2E suite
+
+### C) Update E2E Tests
+If code changes affect user flows, update E2E test specs:
+- New pages/routes → create new E2E specs
+- Changed UI elements (selectors, text, layout) → update locators and assertions
+- Changed form fields or validation → update form fill steps and error assertions
+- New features → add E2E specs covering the happy path + key error cases
+- Removed features → remove or update affected E2E specs
+
+### D) Capture Results
+For all test types:
 - PASS: Test still valid
 - FAIL: Test needs update or code has bug
 - ERROR: Test broken (import error, etc.)
@@ -101,11 +131,13 @@ Create/update `.gsd-t/test-coverage.md`:
 
 ## Summary
 - Source files analyzed: {N}
-- Test files found: {N}
+- Unit/integration test files: {N}
+- E2E test specs: {N}
 - Coverage gaps: {N}
 - Stale tests: {N}
 - Dead tests: {N}
-- Tests passing: {N}/{total}
+- Unit tests passing: {N}/{total}
+- E2E tests passing: {N}/{total}
 
 ## Coverage Status
 
@@ -205,17 +237,20 @@ If issues found, add to current domain's tasks:
 ### During Execute Phase (auto-invoked):
 After each task completes:
 1. Quick scan of changed files
-2. Run affected tests
-3. If failures: pause and report
-4. If gaps: note for end-of-phase sync
-5. Continue execution
+2. Run affected unit/integration tests
+3. Run affected E2E tests (if E2E framework detected)
+4. If failures: pause and report
+5. If E2E specs need updating: update them before continuing
+6. If gaps: note for end-of-phase sync
+7. Continue execution
 
 ### During Verify Phase (auto-invoked):
 Full sync:
-1. Complete coverage analysis
-2. Run all tests
-3. Generate full report
-4. Block verification if critical tests failing
+1. Complete coverage analysis (unit + E2E)
+2. Run ALL unit/integration tests
+3. Run the FULL E2E test suite — this is mandatory, not optional
+4. Generate full report
+5. Block verification if any critical tests failing (unit or E2E)
 
 ### Standalone Mode:
 ```
@@ -238,19 +273,27 @@ Full sync:
 ```
 🧪 Test Sync Complete
 
-Results:
+Unit/Integration:
 - Tests run: 45
 - Passing: 43
 - Failing: 2
-- Coverage gaps: 3
+
+E2E ({framework}):
+- Specs run: 12
+- Passing: 11
+- Failing: 1
+
+Coverage:
+- Gaps: 3
 - Stale tests: 1
 - Dead tests: 0
 
 Action Required:
-- 2 failing tests must be fixed before verify passes
+- 2 failing unit tests must be fixed before verify passes
+- 1 failing E2E spec must be fixed before verify passes
 - See .gsd-t/test-coverage.md for details
 
-Generated 4 test tasks → added to current domain
+Generated 5 test tasks → added to current domain
 ```
 
 $ARGUMENTS

package/commands/gsd-t-verify.md

@@ -20,8 +20,9 @@ Standard dimensions (adjust based on project):
 2. **Contract Compliance**: Does every domain honor its contracts?
 3. **Code Quality**: Conventions, patterns, error handling, readability
 4. **Test Coverage**: Are critical paths tested? Are edge cases covered?
-5. **Security**: Auth flows, input validation, data exposure, dependencies
-6. **Integration Integrity**: Do the seams between domains hold under stress?
+5. **E2E Tests**: Run the full E2E suite (Playwright, Cypress, etc.) — all specs must pass
+6. **Security**: Auth flows, input validation, data exposure, dependencies
+7. **Integration Integrity**: Do the seams between domains hold under stress?
 
 ## Step 3: Execute Verification
 
@@ -32,6 +33,13 @@ Work through each dimension sequentially. For each:
 3. Record findings as PASS / WARN / FAIL with specifics
 4. If FAIL, create a remediation task
 
+**Mandatory test execution:**
+1. Run ALL unit/integration tests — every test must pass
+2. Detect E2E framework (check for `playwright.config.*`, `cypress.config.*`, E2E deps in package.json)
+3. If E2E framework exists, run the FULL E2E suite — every spec must pass
+4. If E2E specs are missing or stale, invoke `gsd-t-test-sync` to update them first, then re-run
+5. Tests are NOT optional — verification cannot pass without running them
+
 ### Team Mode (when agent teams are enabled)
 ```
 Create an agent team for verification:
@@ -88,6 +96,8 @@ Create or update `.gsd-t/verify-report.md`:
 - Functional: {PASS/WARN/FAIL} — {X}/{Y} criteria met
 - Contracts: {PASS/WARN/FAIL} — {X}/{Y} contracts compliant
 - Code Quality: {PASS/WARN/FAIL} — {N} issues found
+- Unit Tests: {PASS/WARN/FAIL} — {N}/{total} passing
+- E2E Tests: {PASS/WARN/FAIL} — {N}/{total} specs passing
 - Security: {PASS/WARN/FAIL} — {N} findings
 - Integration: {PASS/WARN/FAIL}
 

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.2",
+  "version": "2.2.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
@@ -116,8 +133,12 @@ BEFORE EVERY COMMIT:
   │     YES → Update .gsd-t/techdebt.md
   ├── Did I establish a pattern future work should follow?
   │     YES → Update CLAUDE.md or domain constraints.md
-  └── Did I add/change tests?
-        YES → Verify test names and paths are referenced in requirements
+  ├── Did I add/change tests?
+  │     YES → Verify test names and paths are referenced in requirements
+  ├── Did I change UI, routes, or user flows?
+  │     YES → Update affected E2E test specs (Playwright/Cypress)
+  └── Did I run the affected tests?
+        YES → Verify they pass. NO → Run them now.
 ```
 
 If ANY answer is YES and the doc is NOT updated, update it BEFORE committing. No exceptions.

package/templates/progress.md

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