pi-gsd 1.0.3

package/package.json

@@ -0,0 +1,72 @@
+{
+	"name": "pi-gsd",
+	"version": "1.0.3",
+	"description": "Get Shit Done - Unofficial port of the renowned AI-native project-planning spec-driven toolkit",
+	"main": "dist/gsd-tools.js",
+	"bin": {
+		"gsd-tools": "./dist/gsd-tools.js",
+		"pi-gsd": "./dist/gsd-tools.js"
+	},
+	"scripts": {
+		"build": "tsup src/cli.ts --format cjs --out-dir dist --minify --no-splitting && mv dist/cli.js dist/gsd-tools.js && chmod +x dist/gsd-tools.js",
+		"dev": "tsup src/cli.ts --format cjs --out-dir dist --watch",
+		"typecheck": "tsc --noEmit",
+		"build:harnesses": "node scripts/build-harnesses.js --clean",
+		"postinstall": "node scripts/postinstall.js",
+		"prepublishOnly": "npm run build && node scripts/build-harnesses.js --clean"
+	},
+	"files": [
+		"skills",
+		"dist",
+		"scripts/postinstall.js",
+		"README.md",
+		"LICENSE"
+	],
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"keywords": [
+		"ai",
+		"agent",
+		"planning",
+		"cli",
+		"workflow",
+		"get-shit-done",
+		"gsd",
+		"productivity",
+		"project-management",
+		"milestones",
+		"phases",
+		"spec",
+		"pi-package"
+	],
+	"author": "Alessio Corsi",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/fulgidus/pi-gsd.git"
+	},
+	"bugs": {
+		"url": "https://github.com/fulgidus/pi-gsd/issues"
+	},
+	"homepage": "https://github.com/fulgidus/pi-gsd#readme",
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"pi": {
+		"skills": [
+			"./skills"
+		]
+	},
+	"dependencies": {
+		"@toon-format/toon": "^2.1.0",
+		"commander": "^13.0.0",
+		"jsonpath-plus": "^10.4.0"
+	},
+	"devDependencies": {
+		"tsup": "^8.0.0",
+		"typescript": "^5.0.0",
+		"@types/node": "^22.0.0"
+	}
+}

package/scripts/postinstall.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * postinstall.js - GSD harness installer
+ *
+ * Runs automatically after `npm install get-shit-done-cc`.
+ * Copies each AI-platform harness directory from this package's
+ * `.gsd/harnesses/<harness>/` into the consumer project's root
+ * so the AI agent can discover the GSD workflows, commands, hooks,
+ * and CLI binary at the expected platform-native paths.
+ *
+ * Harness layout inside this package (source):
+ *   .gsd/harnesses/
+ *     agent/     → consumer project root: .agent/get-shit-done/
+ *     claude/    → consumer project root: .claude/get-shit-done/
+ *     codex/     → consumer project root: .codex/get-shit-done/
+ *     cursor/    → consumer project root: .cursor/get-shit-done/
+ *     gemini/    → consumer project root: .gemini/get-shit-done/
+ *     github/    → consumer project root: .github/get-shit-done/
+ *     opencode/  → consumer project root: .opencode/get-shit-done/
+ *     windsurf/  → consumer project root: .windsurf/get-shit-done/
+ *
+ * Hook files are also copied from `.gsd/hooks/` into each harness
+ * that supports the GSD hook system.
+ *
+ * The script is intentionally defensive: it never overwrites files
+ * that already exist (use --force-reinstall env flag to override),
+ * and it skips silently if a harness source directory is absent
+ * from the package (forward-compatibility).
+ *
+ * @see README.md §3 (Installation) for usage details.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const FORCE = process.env.GSD_FORCE_REINSTALL === '1'
+    || process.argv.includes('--force-reinstall');
+
+/**
+ * Directory that contains this package's files.
+ * When executed via npm postinstall, __dirname is the package root.
+ */
+const PKG_DIR = path.resolve(__dirname, '..');
+
+/**
+ * The consuming project's root.
+ * npm sets INIT_CWD to the directory where `npm install` was run.
+ * Fall back to process.cwd() for programmatic / npx usage.
+ */
+const PROJECT_ROOT = process.env.INIT_CWD || process.cwd();
+
+/**
+ * Harness definitions.
+ *
+ * Each entry maps:
+ *   src  - subdirectory under <package>/.gsd/harnesses/
+ *   dest - directory in the consumer project root
+ *   hooks - whether this platform supports GSD hooks (copied from .gsd/hooks/)
+ */
+const HARNESSES = [
+    { src: 'agent', dest: '.agent', hooks: true },
+    { src: 'claude', dest: '.claude', hooks: true },
+    { src: 'codex', dest: '.codex', hooks: false },
+    { src: 'cursor', dest: '.cursor', hooks: false },
+    { src: 'gemini', dest: '.gemini', hooks: true },
+    { src: 'github', dest: '.github', hooks: false },
+    { src: 'opencode', dest: '.opencode', hooks: true },
+    { src: 'windsurf', dest: '.windsurf', hooks: false },
+];
+
+/**
+ * Subdirectory name used inside each harness's dest folder for
+ * GSD-specific content (workflows, bin, references, templates …).
+ */
+const GSD_SUBDIR = 'get-shit-done';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Recursively copy a directory tree from `src` to `dest`.
+ * If `overwrite` is false (default), existing files are left untouched.
+ *
+ * @param {string} src       Absolute source path
+ * @param {string} dest      Absolute destination path
+ * @param {boolean} overwrite Replace existing files when true
+ * @returns {{ copied: number, skipped: number }}
+ */
+function copyDir(src, dest, overwrite) {
+    let copied = 0;
+    let skipped = 0;
+
+    if (!fs.existsSync(src)) return { copied, skipped };
+
+    fs.mkdirSync(dest, { recursive: true });
+
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcEntry = path.join(src, entry.name);
+        const destEntry = path.join(dest, entry.name);
+
+        if (entry.isDirectory()) {
+            const sub = copyDir(srcEntry, destEntry, overwrite);
+            copied += sub.copied;
+            skipped += sub.skipped;
+        } else if (entry.isFile()) {
+            if (!overwrite && fs.existsSync(destEntry)) {
+                skipped++;
+            } else {
+                fs.copyFileSync(srcEntry, destEntry);
+                copied++;
+            }
+        }
+    }
+
+    return { copied, skipped };
+}
+
+/**
+ * Emit a coloured status line to stdout.
+ * Colours are stripped when stdout is not a TTY (CI / pipe).
+ *
+ * @param {'ok'|'skip'|'warn'|'err'} level
+ * @param {string} msg
+ */
+function log(level, msg) {
+    const isTTY = process.stdout.isTTY;
+    const colours = {
+        ok: isTTY ? '\x1b[32m✓\x1b[0m' : '✓',
+        skip: isTTY ? '\x1b[33m–\x1b[0m' : '–',
+        warn: isTTY ? '\x1b[33m⚠\x1b[0m' : '⚠',
+        err: isTTY ? '\x1b[31m✗\x1b[0m' : '✗',
+    };
+    console.log(`  ${colours[level] || ' '} ${msg}`);
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+function main() {
+    // Skip when running inside the package's own development tree
+    // (i.e. when INIT_CWD === the package directory itself).
+    if (path.resolve(PROJECT_ROOT) === path.resolve(PKG_DIR)) {
+        log('skip', 'Running inside package source tree - skipping harness install.');
+        return;
+    }
+
+    // Skip when explicitly opted out
+    if (process.env.GSD_SKIP_INSTALL === '1') {
+        log('skip', 'GSD_SKIP_INSTALL=1 - skipping harness install.');
+        return;
+    }
+
+    const harnessesRoot = path.join(PKG_DIR, '.gsd', 'harnesses');
+    const hooksRoot = path.join(PKG_DIR, '.gsd', 'hooks');
+
+    console.log('');
+    console.log('  GSD - installing harness files into your project…');
+    if (FORCE) console.log('  (force-reinstall mode: existing files will be overwritten)');
+    console.log('');
+
+    let totalCopied = 0;
+    let totalSkipped = 0;
+    let installed = 0;
+
+    for (const harness of HARNESSES) {
+        const srcHarness = path.join(harnessesRoot, harness.src);
+        const destHarness = path.join(PROJECT_ROOT, harness.dest);
+
+        // ── get-shit-done/ content ──────────────────────────────────────────────
+        const srcGsd = path.join(srcHarness, GSD_SUBDIR);
+        const destGsd = path.join(destHarness, GSD_SUBDIR);
+
+        if (!fs.existsSync(srcHarness)) {
+            log('skip', `${harness.dest}/${GSD_SUBDIR}  (source absent - skipped)`);
+            continue;
+        }
+
+        const { copied, skipped } = copyDir(srcGsd, destGsd, FORCE);
+        totalCopied += copied;
+        totalSkipped += skipped;
+
+        if (copied > 0 || skipped === 0) {
+            log('ok', `${harness.dest}/${GSD_SUBDIR}  (${copied} file${copied === 1 ? '' : 's'} installed)`);
+        } else {
+            log('skip', `${harness.dest}/${GSD_SUBDIR}  (already up-to-date, ${skipped} file${skipped === 1 ? '' : 's'} skipped)`);
+        }
+
+        // ── gsd-file-manifest.json ──────────────────────────────────────────────
+        const manifestSrc = path.join(srcHarness, 'gsd-file-manifest.json');
+        const manifestDest = path.join(destHarness, 'gsd-file-manifest.json');
+
+        if (fs.existsSync(manifestSrc)) {
+            if (!FORCE && fs.existsSync(manifestDest)) {
+                totalSkipped++;
+            } else {
+                fs.mkdirSync(destHarness, { recursive: true });
+                fs.copyFileSync(manifestSrc, manifestDest);
+                totalCopied++;
+            }
+        }
+
+        // ── hooks/ (platform-selective) ─────────────────────────────────────────
+        if (harness.hooks && fs.existsSync(hooksRoot)) {
+            const destHooks = path.join(destHarness, 'hooks');
+            const h = copyDir(hooksRoot, destHooks, FORCE);
+            totalCopied += h.copied;
+            totalSkipped += h.skipped;
+
+            if (h.copied > 0) {
+                log('ok', `${harness.dest}/hooks  (${h.copied} hook${h.copied === 1 ? '' : 's'} installed)`);
+            }
+        }
+
+        // ── skills/ (opencode only - present in .gsd/harnesses/opencode/skills) ─
+        const srcSkills = path.join(srcHarness, 'skills');
+        const destSkills = path.join(destHarness, 'skills');
+
+        if (fs.existsSync(srcSkills)) {
+            const s = copyDir(srcSkills, destSkills, FORCE);
+            totalCopied += s.copied;
+            totalSkipped += s.skipped;
+
+            if (s.copied > 0) {
+                log('ok', `${harness.dest}/skills  (${s.copied} skill file${s.copied === 1 ? '' : 's'} installed)`);
+            }
+        }
+
+        installed++;
+    }
+
+    console.log('');
+
+    if (installed === 0) {
+        log('warn', 'No harness source directories found inside the package.');
+        log('warn', 'The package may be incomplete. Try: npm install --force get-shit-done-cc');
+        console.log('');
+        return;
+    }
+
+    console.log(`  GSD v${getPackageVersion()} installed successfully.`);
+    console.log(`  ${totalCopied} file${totalCopied === 1 ? '' : 's'} copied, ${totalSkipped} skipped.`);
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    • Claude / Gemini / Cursor / OpenCode: run /gsd:new-project');
+    console.log('    • Claude Code (.agent):                run /gsd-new-project');
+    console.log('    • Codex:                               run $gsd-new-project');
+    console.log('    • GitHub Copilot:                      run /gsd:new-project');
+    console.log('');
+    console.log('  Docs: https://github.com/fulgidus/pi-gsd#readme');
+    console.log('');
+}
+
+/**
+ * Read the version from this package's own package.json.
+ * Gracefully returns 'unknown' if the file is unreadable.
+ *
+ * @returns {string}
+ */
+function getPackageVersion() {
+    try {
+        const pkg = JSON.parse(
+            fs.readFileSync(path.join(PKG_DIR, 'package.json'), 'utf8')
+        );
+        return pkg.version || 'unknown';
+    } catch {
+        return 'unknown';
+    }
+}
+
+main();

package/skills/gsd-add-backlog/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: gsd-add-backlog
+description: Add an idea to the backlog parking lot (999.x numbering)
+---
+
+<objective>
+Add a backlog item to the roadmap using 999.x numbering. Backlog items are
+unsequenced ideas that aren't ready for active planning - they live outside
+the normal phase sequence and accumulate context over time.
+</objective>
+
+<process>
+
+1. **Read ROADMAP.md** to find existing backlog entries:
+
+   ```bash
+   cat .planning/ROADMAP.md
+   ```
+
+2. **Find next backlog number:**
+
+   ```bash
+   NEXT=$(node ".agent/get-shit-done/bin/gsd-tools.cjs" phase next-decimal 999 --raw)
+   ```
+
+   If no 999.x phases exist, start at 999.1.
+
+3. **Create the phase directory:**
+
+   ```bash
+   SLUG=$(node ".agent/get-shit-done/bin/gsd-tools.cjs" generate-slug "$ARGUMENTS")
+   mkdir -p ".planning/phases/${NEXT}-${SLUG}"
+   touch ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
+   ```
+
+4. **Add to ROADMAP.md** under a `## Backlog` section. If the section doesn't exist, create it at the end:
+
+   ```markdown
+   ## Backlog
+
+   ### Phase {NEXT}: {description} (BACKLOG)
+
+   **Goal:** [Captured for future planning]
+   **Requirements:** TBD
+   **Plans:** 0 plans
+
+   Plans:
+
+   - [ ] TBD (promote with /gsd-review-backlog when ready)
+   ```
+
+5. **Commit:**
+
+   ```bash
+   node ".agent/get-shit-done/bin/gsd-tools.cjs" commit "docs: add backlog item ${NEXT} - ${ARGUMENTS}" --files .planning/ROADMAP.md ".planning/phases/${NEXT}-${SLUG}/.gitkeep"
+   ```
+
+6. **Report:**
+
+   ```
+   ## 📋 Backlog Item Added
+
+   Phase {NEXT}: {description}
+   Directory: .planning/phases/{NEXT}-{slug}/
+
+   This item lives in the backlog parking lot.
+   Use /gsd-discuss-phase {NEXT} to explore it further.
+   Use /gsd-review-backlog to promote items to active milestone.
+   ```
+
+</process>
+
+<notes>
+- 999.x numbering keeps backlog items out of the active phase sequence
+- Phase directories are created immediately, so /gsd-discuss-phase and /gsd-plan-phase work on them
+- No `Depends on:` field - backlog items are unsequenced by definition
+- Sparse numbering is fine (999.1, 999.3) - always uses next-decimal
+</notes>

package/skills/gsd-add-phase/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: gsd-add-phase
+description: Add phase to end of current milestone in roadmap
+---
+
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+Routes to the add-phase workflow which handles:
+- Phase number calculation (next sequential integer)
+- Directory creation with slug generation
+- Roadmap structure updates
+- STATE.md roadmap evolution tracking
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/add-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (phase description)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
+<process>
+**Follow the add-phase workflow** from `@.agent/get-shit-done/workflows/add-phase.md`.
+
+The workflow handles all logic including:
+1. Argument parsing and validation
+2. Roadmap existence checking
+3. Current milestone identification
+4. Next phase number calculation (ignoring decimals)
+5. Slug generation from description
+6. Phase directory creation
+7. Roadmap entry insertion
+8. STATE.md updates
+</process>

package/skills/gsd-add-tests/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: gsd-add-tests
+description: Generate tests for a completed phase based on UAT criteria and implementation
+---
+
+<objective>
+Generate unit and E2E tests for a completed phase, using its SUMMARY.md, CONTEXT.md, and VERIFICATION.md as specifications.
+
+Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
+
+Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/add-tests.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+Execute the add-tests workflow from @.agent/get-shit-done/workflows/add-tests.md end-to-end.
+Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
+</process>

package/skills/gsd-add-todo/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: gsd-add-todo
+description: Capture idea or task as todo from current conversation context
+---
+
+
+<objective>
+Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work.
+
+Routes to the add-todo workflow which handles:
+- Directory structure creation
+- Content extraction from arguments or conversation
+- Area inference from file paths
+- Duplicate detection and resolution
+- Todo file creation with frontmatter
+- STATE.md updates
+- Git commits
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/add-todo.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional todo description)
+
+State is resolved in-workflow via `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the add-todo workflow** from `@.agent/get-shit-done/workflows/add-todo.md`.
+
+The workflow handles all logic including:
+1. Directory ensuring
+2. Existing area checking
+3. Content extraction (arguments or conversation)
+4. Area inference
+5. Duplicate checking
+6. File creation with slug generation
+7. STATE.md updates
+8. Git commits
+</process>

package/skills/gsd-audit-milestone/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: gsd-audit-milestone
+description: Audit milestone completion against original intent before archiving
+---
+
+<objective>
+Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
+
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/audit-milestone.md
+</execution_context>
+
+<context>
+Version: $ARGUMENTS (optional - defaults to current milestone)
+
+Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
+
+**Completed Work:**
+Glob: .planning/phases/_/_-SUMMARY.md
+Glob: .planning/phases/_/_-VERIFICATION.md
+</context>
+
+<process>
+Execute the audit-milestone workflow from @.agent/get-shit-done/workflows/audit-milestone.md end-to-end.
+Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
+</process>

package/skills/gsd-audit-uat/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: gsd-audit-uat
+description: Cross-phase audit of all outstanding UAT and verification items
+---
+
+<objective>
+Scan all phases for pending, skipped, blocked, and human_needed UAT items. Cross-reference against codebase to detect stale documentation. Produce prioritized human test plan.
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/audit-uat.md
+</execution_context>
+
+<context>
+Core planning files are loaded in-workflow via CLI.
+
+**Scope:**
+Glob: .planning/phases/*/*-UAT.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>

package/skills/gsd-autonomous/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: gsd-autonomous
+description: Run all remaining phases autonomously - discuss→plan→execute per phase
+---
+
+<objective>
+Execute all remaining milestone phases autonomously. For each phase: discuss → plan → execute. Pauses only for user decisions (grey area acceptance, blockers, validation requests).
+
+Uses ROADMAP.md phase discovery and Skill() flat invocations for each phase command. After all phases complete: milestone audit → complete → cleanup.
+
+**Creates/Updates:**
+
+- `.planning/STATE.md` - updated after each phase
+- `.planning/ROADMAP.md` - progress updated after each phase
+- Phase artifacts - CONTEXT.md, PLANs, SUMMARYs per phase
+
+**After:** Milestone is complete and cleaned up.
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/autonomous.md
+@.agent/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<context>
+Optional flag: `--from N` - start from phase N instead of the first incomplete phase.
+
+Project context, phase list, and state are resolved inside the workflow using init commands (`gsd-tools.cjs init milestone-op`, `gsd-tools.cjs roadmap analyze`). No upfront context loading needed.
+</context>
+
+<process>
+Execute the autonomous workflow from @.agent/get-shit-done/workflows/autonomous.md end-to-end.
+Preserve all workflow gates (phase discovery, per-phase execution, blocker handling, progress display).
+</process>

package/skills/gsd-check-todos/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: gsd-check-todos
+description: List pending todos and select one to work on
+---
+
+
+<objective>
+List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
+
+Routes to the check-todos workflow which handles:
+- Todo counting and listing with area filtering
+- Interactive selection with full context loading
+- Roadmap correlation checking
+- Action routing (work now, add to phase, brainstorm, create phase)
+- STATE.md updates and git commits
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/check-todos.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional area filter)
+
+Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the check-todos workflow** from `@.agent/get-shit-done/workflows/check-todos.md`.
+
+The workflow handles all logic including:
+1. Todo existence checking
+2. Area filtering
+3. Interactive listing and selection
+4. Full context loading with file summaries
+5. Roadmap correlation checking
+6. Action offering and execution
+7. STATE.md updates
+8. Git commits
+</process>

package/skills/gsd-cleanup/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: gsd-cleanup
+description: Archive accumulated phase directories from completed milestones
+---
+
+<objective>
+Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
+
+Use when `.planning/phases/` has accumulated directories from past milestones.
+</objective>
+
+<execution_context>
+@.agent/get-shit-done/workflows/cleanup.md
+</execution_context>
+
+<process>
+Follow the cleanup workflow at @.agent/get-shit-done/workflows/cleanup.md.
+Identify completed milestones, show a dry-run summary, and archive on confirmation.
+</process>