@tekyzinc/gsd-t 2.21.0 → 2.23.0

package/docs/architecture.md

@@ -0,0 +1,82 @@
+# Architecture — GSD-T Framework (@tekyzinc/gsd-t)
+
+## Last Updated: 2026-02-18
+
+## System Overview
+
+GSD-T is an npm-distributed methodology framework for Claude Code. It provides slash commands (markdown files), a CLI installer (Node.js), and document templates that together enable contract-driven development with AI assistance.
+
+The framework has no runtime — it is consumed entirely by Claude Code's slash command system and the user's shell. The CLI handles installation, updates, and diagnostics. The command files define the workflow methodology that Claude Code follows.
+
+## Components
+
+### CLI Installer (bin/gsd-t.js)
+- **Purpose**: Install, update, diagnose, and manage GSD-T across projects
+- **Location**: `bin/gsd-t.js`
+- **Dependencies**: Node.js built-ins only (fs, path, os, child_process, https)
+- **Subcommands**: install, update, status, doctor, init, uninstall, update-all, register, changelog
+
+### Slash Commands (commands/*.md)
+- **Purpose**: Define the GSD-T methodology as executable workflows for Claude Code
+- **Location**: `commands/`
+- **Count**: 41 (37 GSD-T workflow + 4 utility)
+- **Format**: Pure markdown with step-numbered instructions, team mode blocks, and document ripple sections
+
+### Templates (templates/*.md)
+- **Purpose**: Starter files for project initialization
+- **Location**: `templates/`
+- **Count**: 9 (CLAUDE-global, CLAUDE-project, requirements, architecture, workflows, infrastructure, progress, backlog, backlog-settings)
+- **Tokens**: `{Project Name}`, `{Date}`, `{app}` replaced during init
+
+### Heartbeat System (scripts/gsd-t-heartbeat.js)
+- **Purpose**: Real-time event logging via Claude Code hooks
+- **Location**: `scripts/gsd-t-heartbeat.js`
+- **Output**: `.gsd-t/heartbeat-{session}.jsonl` files
+
+### Examples (examples/)
+- **Purpose**: Reference project structure and settings
+- **Location**: `examples/`
+- **Contents**: settings.json, .gsd-t/ with sample contracts and domain structure
+
+## Data Models
+
+### Progress State (.gsd-t/progress.md)
+| Field | Type | Notes |
+|-------|------|-------|
+| Project | string | Name from CLAUDE.md |
+| Version | semver | Major.Minor.Patch |
+| Status | enum | INITIALIZED, IN_PROGRESS, READY |
+| Current Milestone | string | Active milestone name or "None" |
+| Decision Log | entries | Timestamped log of all changes |
+
+### Backlog (.gsd-t/backlog.md)
+| Field | Type | Notes |
+|-------|------|-------|
+| ID | Bn | Sequential backlog item ID |
+| Type | enum | bug, feature, improvement, ux, architecture |
+| App | string | Target application |
+| Category | string | Domain/module category |
+| Description | string | Item summary |
+
+### Contracts (.gsd-t/contracts/)
+| Contract | Purpose |
+|----------|---------|
+| command-interface-contract.md | Slash command file format and structure |
+| file-format-contract.md | File naming and organization rules |
+| integration-points.md | How components connect |
+| backlog-file-formats.md | Backlog markdown structure |
+| domain-structure.md | Domain directory layout |
+| pre-commit-gate.md | Commit checklist contract |
+| progress-file-format.md | Progress.md structure |
+| wave-phase-sequence.md | Phase ordering rules |
+
+## Design Decisions
+
+| Date | Decision | Rationale | Alternatives Considered |
+|------|----------|-----------|------------------------|
+| 2026-02-07 | Zero external dependencies for CLI | Simplicity, no install failures, no supply chain risk | Using commander.js, yargs |
+| 2026-02-07 | Markdown-only command files | Claude Code native format, no build step, human-readable | YAML frontmatter, JSON config |
+| 2026-02-09 | Semantic versioning with git tags | Standard npm practice, enables update checks | CalVer, build numbers |
+| 2026-02-12 | Heartbeat via Claude Code hooks | Non-invasive monitoring, no command file changes needed | Polling, WebSocket |
+| 2026-02-13 | Semantic router over keyword matching | Better intent detection, fewer misroutes | Regex patterns, ML classifier |
+| 2026-02-16 | Mandatory Playwright for all projects | Consistent E2E testing, no "we'll add tests later" | Optional testing, Jest-only |

package/docs/infrastructure.md

@@ -0,0 +1,72 @@
+# Infrastructure — GSD-T Framework (@tekyzinc/gsd-t)
+
+## Last Updated: 2026-02-18
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Install GSD-T | `npx @tekyzinc/gsd-t install` |
+| Check status | `npx @tekyzinc/gsd-t status` |
+| Update GSD-T | `npx @tekyzinc/gsd-t update` |
+| Update all projects | `npx @tekyzinc/gsd-t update-all` |
+| Diagnose issues | `npx @tekyzinc/gsd-t doctor` |
+| View changelog | `npx @tekyzinc/gsd-t changelog` |
+| Publish to npm | `npm publish` |
+
+## Local Development
+
+### Setup
+```bash
+# Clone and install
+git clone https://github.com/Tekyz-Inc/get-stuff-done-teams.git
+cd get-stuff-done-teams
+
+# No npm install needed — zero dependencies
+# Test the CLI directly:
+node bin/gsd-t.js status
+```
+
+### Testing
+```bash
+# Test CLI subcommands
+node bin/gsd-t.js install
+node bin/gsd-t.js status
+node bin/gsd-t.js doctor
+node bin/gsd-t.js init test-project
+
+# Validate command files exist
+ls commands/*.md | wc -l  # Should be 41
+ls templates/*.md | wc -l  # Should be 9
+```
+
+## Distribution
+
+### npm Package
+- **Registry**: https://www.npmjs.com/package/@tekyzinc/gsd-t
+- **Publish**: `npm publish` (requires npm login with Tekyz account)
+- **Version**: Managed in `package.json`, synced to `.gsd-t/progress.md`
+
+### Installed Locations
+| What | Where |
+|------|-------|
+| Slash commands | `~/.claude/commands/` |
+| Global config | `~/.claude/CLAUDE.md` |
+| Heartbeat hook | `~/.claude/settings.json` (hooks section) |
+| Version cache | `~/.claude/.gsd-t-version` |
+| Update cache | `~/.claude/.gsd-t-update-cache` |
+| Project registry | `~/.claude/.gsd-t-projects` |
+
+## Repository Structure
+
+```
+get-stuff-done-teams/
+├── bin/gsd-t.js        — CLI (zero dependencies)
+├── commands/           — 41 slash command files
+├── templates/          — 9 document templates
+├── scripts/            — Heartbeat hook script
+├── examples/           — Reference project structure
+├── docs/               — Methodology + living docs
+├── .gsd-t/             — GSD-T state (self-managed)
+└── package.json        — npm package config
+```

package/docs/requirements.md

@@ -0,0 +1,43 @@
+# Requirements — GSD-T Framework (@tekyzinc/gsd-t)
+
+## Last Updated: 2026-02-18
+
+## Functional Requirements
+
+| ID | Requirement | Priority | Status | Tests |
+|----|-------------|----------|--------|-------|
+| REQ-001 | CLI installer with install, update, status, doctor, init, uninstall, update-all, register, changelog subcommands | P1 | complete | manual CLI testing |
+| REQ-002 | 37 GSD-T workflow slash commands for Claude Code | P1 | complete | validated by use |
+| REQ-003 | 4 utility commands (branch, checkin, Claude-md, gsd smart router) | P1 | complete | validated by use |
+| REQ-004 | Backlog management system (7 commands: add, list, move, edit, remove, promote, settings) | P1 | complete | validated by use |
+| REQ-005 | Contract-driven development with domain partitioning | P1 | complete | validated by use |
+| REQ-006 | Wave orchestration (full cycle: partition → plan → execute → test-sync → integrate → verify) | P1 | complete | validated by use |
+| REQ-007 | Heartbeat system via Claude Code hooks | P2 | complete | hook scripts installed |
+| REQ-008 | Automatic update check against npm registry | P2 | complete | CLI + slash command |
+| REQ-009 | Document templates for living docs (9 templates) | P1 | complete | used by gsd-t-init |
+| REQ-010 | Smart router — natural language intent → command routing | P2 | complete | validated by use |
+
+## Technical Requirements
+
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| TECH-001 | Zero external npm dependencies | P1 | complete |
+| TECH-002 | Node.js >= 16 compatibility | P1 | complete |
+| TECH-003 | Cross-platform support (macOS, Linux, Windows) | P1 | complete |
+| TECH-004 | Semantic versioning with git tags | P1 | complete |
+| TECH-005 | Pre-Commit Gate enforced on every commit | P1 | complete |
+
+## Non-Functional Requirements
+
+| ID | Requirement | Metric | Status |
+|----|-------------|--------|--------|
+| NFR-001 | CLI install completes in < 5 seconds | < 5s | complete |
+| NFR-002 | No runtime crashes on missing files | graceful fallback | complete |
+| NFR-003 | Command files are pure markdown (no frontmatter) | 100% compliance | complete |
+
+## Test Coverage
+
+| Requirement | Test File | Test Name | Status |
+|-------------|-----------|-----------|--------|
+| REQ-001 | manual | CLI subcommand testing | passing |
+| REQ-002–010 | manual | Workflow validation by use | passing |

package/docs/workflows.md

@@ -0,0 +1,67 @@
+# Workflows — GSD-T Framework (@tekyzinc/gsd-t)
+
+## Last Updated: 2026-02-18
+
+## User Workflows
+
+### Install GSD-T
+1. Run `npx @tekyzinc/gsd-t install`
+2. CLI copies commands to `~/.claude/commands/`
+3. CLI sets up global CLAUDE.md if missing
+4. CLI installs heartbeat hooks
+5. User starts Claude Code in their project
+
+**Entry point**: `npx @tekyzinc/gsd-t install`
+**Success**: 41 commands available in Claude Code
+**Failure**: CLI reports missing Node.js or permission errors
+
+### Initialize a Project
+1. User runs `/gsd-t-init` in Claude Code
+2. Init creates `.gsd-t/` directory structure
+3. Init creates or updates CLAUDE.md
+4. Init creates `docs/` living documents if missing
+5. Init scans existing codebase if code exists
+
+**Entry point**: `/gsd-t-init` slash command
+**Success**: Project ready for milestone definition
+**Failure**: Reports what couldn't be created
+
+### Full Wave Cycle
+1. User defines milestone via `/gsd-t-milestone`
+2. Partition decomposes into domains + contracts
+3. Plan creates task lists per domain
+4. Execute implements tasks (solo or team)
+5. Test-sync aligns tests with code changes
+6. Integrate wires domains together
+7. Verify runs quality gates
+8. Complete-milestone archives and tags
+
+**Entry point**: `/gsd-t-wave` or manual phase-by-phase
+**Success**: Milestone completed, version bumped, git tagged
+**Failure**: Wave pauses at failing phase, user can fix and resume
+
+## Technical Workflows
+
+### CLI Update Check
+1. CLI reads cached version from `~/.claude/.gsd-t-update-cache`
+2. If cache is older than 1 hour, query npm registry
+3. Compare installed vs. latest using semver
+4. Display update notice if newer version available
+
+**Trigger**: Every CLI invocation and `/gsd-t-status`
+**Frequency**: Cached, actual fetch at most once per hour
+
+### Heartbeat Event Logging
+1. Claude Code hook fires on tool call or notification
+2. `gsd-t-heartbeat.js` appends JSONL event to `.gsd-t/heartbeat-{session}.jsonl`
+3. Events include timestamp, type, and context
+
+**Trigger**: Claude Code hooks (9 event types)
+**Frequency**: On every hooked event during a session
+
+## Integration Workflows
+
+### npm Publish
+- **Trigger**: Manual `npm publish` after milestone completion
+- **Flow**: Version bumped → CHANGELOG updated → git tagged → npm publish
+- **Verification**: `npx @tekyzinc/gsd-t status` on fresh install

package/examples/.gsd-t/domains/example-domain/scope.md

@@ -1,15 +1,13 @@
-# Domain: auth — Example
-
-## Responsibility
-Handles all authentication and authorization: user registration, login, JWT token generation and verification, password hashing, and auth middleware for protecting routes.
-
-## Files Owned
-- `src/auth/` — all auth service code
-- `src/middleware/auth.py` — auth middleware
-- `tests/auth/` — auth tests
-
-## Inputs (from other domains)
-- schema-contract.md: Users table structure for lookups
-
-## Outputs (to other domains)
-- api-contract.md: POST /api/auth/login, POST /api/auth/register, GET /api/users/me
+# Domain: auth — Example
+
+## Responsibility
+Handles all authentication and authorization: user registration, login, JWT token generation and verification, password hashing, and auth middleware for protecting routes.
+
+## Owned Files/Directories
+- `src/auth/` — all auth service code
+- `src/middleware/auth.py` — auth middleware
+- `tests/auth/` — auth tests
+
+## NOT Owned (do not modify)
+- `src/db/` — owned by data-layer domain
+- `src/api/` — owned by api domain (except auth endpoints)

package/package.json

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

package/scripts/gsd-t-heartbeat.js

@@ -55,6 +55,8 @@ process.stdin.on("end", () => {
     const event = buildEvent(hook);
     if (event) {
       cleanupOldHeartbeats(gsdtDir);
+      // Symlink check — prevent redirection of event data to arbitrary files
+      try { if (fs.lstatSync(file).isSymbolicLink()) return; } catch { /* file doesn't exist yet — safe */ }
       fs.appendFileSync(file, JSON.stringify(event) + "\n");
     }
   } catch (e) {
@@ -69,7 +71,8 @@ function cleanupOldHeartbeats(gsdtDir) {
     for (const f of files) {
       if (!f.startsWith("heartbeat-") || !f.endsWith(".jsonl")) continue;
       const fp = path.join(gsdtDir, f);
-      const stat = fs.statSync(fp);
+      const stat = fs.lstatSync(fp);
+      if (stat.isSymbolicLink()) continue; // Don't follow symlinks
       if (now - stat.mtimeMs > MAX_AGE_MS) {
         fs.unlinkSync(fp);
       }

package/scripts/npm-update-check.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+/**
+ * Background update check — spawned detached by the CLI to refresh the version cache.
+ * Usage: node npm-update-check.js <cache-file-path>
+ */
+
+const https = require("https");
+const fs = require("fs");
+
+const cacheFile = process.argv[2];
+if (!cacheFile) process.exit(1);
+
+https.get("https://registry.npmjs.org/@tekyzinc/gsd-t/latest",
+  { timeout: 5000 }, (res) => {
+  let d = "";
+  res.on("data", (c) => d += c);
+  res.on("end", () => {
+    try {
+      const v = JSON.parse(d).version;
+      if (v && /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/.test(v)) {
+        fs.writeFileSync(cacheFile,
+          JSON.stringify({ latest: v, timestamp: Date.now() }));
+      }
+    } catch { /* malformed response — skip */ }
+  });
+}).on("error", () => {});