gsd-tools

• Load and manage .planning/config.json configuration
• Generate deterministic slugs from descriptions (kebab-case, deduplication)
• Format timestamps for GSD artifact headers and frontmatter
• Resolve paths within the .planning/ directory structure
• Parse and normalize phase numbers (integer and decimal)
• Manage sequential quick task numbering in .planning/quick/
• Initialize and validate .planning/ directory structure
• Detect project state (new project, existing project, mid-phase, etc.)

Capabilities

1. Configuration Loading

Load and parse .planning/config.json with defaults:

{
  "profile": "balanced",
  "autoCommit": true,
  "autoVerify": true,
  "planCheckerEnabled": true,
  "maxPlanRevisions": 2,
  "waveParallelization": true,
  "contextMonitor": true,
  "contextWarningThreshold": 70,
  "contextCriticalThreshold": 85,
  "summaryVariant": "standard",
  "tddEnabled": false,
  "questioningDepth": "adaptive"
}

Read config:

cat .planning/config.json

If config does not exist, create with defaults. Merge user overrides with defaults (user values take precedence).

2. Slug Generation

Generate kebab-case slugs from descriptions:

Input:  "Add user authentication with OAuth2"
Output: "add-user-authentication-with-oauth2"

Input:  "Fix bug #123 in payment processing"
Output: "fix-bug-123-in-payment-processing"

Rules:

• Lowercase all characters
• Replace spaces and special characters with hyphens
• Remove consecutive hyphens
• Trim leading/trailing hyphens
• Maximum 60 characters (truncate at word boundary)
• Check for duplicates in target directory, append -2, -3 if needed

3. Timestamp Formatting

Format timestamps for GSD artifacts:

Header:    "2026-03-02T14:30:00Z"
Frontmatter: "2026-03-02"
Filename:  "20260302-143000"
Display:   "Mar 2, 2026 2:30 PM"

4. Path Operations

Resolve paths within .planning/ structure:

Phase directory:    .planning/phase-{N}/
Plan file:          .planning/phase-{N}/PLAN-{M}.md
Summary file:       .planning/phase-{N}/SUMMARY.md
Quick task:         .planning/quick/{NNN}-{slug}/
Debug session:      .planning/debug/{slug}.md
Codebase docs:      .planning/codebase/
Research docs:      .planning/research/
Milestone archive:  milestones/v{X}.{Y}/