gsd-driver

name	gsd-driver
description	Wraps gsd-pi (Get Shit Done coding agent CLI) with Marcus's project constraints and coding standards so gsd tasks inherit observer pattern, no em-dashes, no Co-Authored-By, and AgenticOS event integration automatically. Use when the user says "run this with gsd", "hand this off to gsd", "use gsd-pi for this", "delegate to gsd", or wants to execute a coding task using gsd-pi as the execution engine rather than Claude Code directly. Also trigger when autonomous-workflow needs to fan out a phase to gsd-pi for execution.
user-invocable	true
argument-hint	<task description or spec file path> [--phase=<phase-name>] [--dry-run]

GSD Driver

Executes coding tasks via gsd-pi with Marcus's constraints pre-applied. Acts as the adapter layer between Claude Code's orchestration and gsd-pi's execution engine.

What This Skill Does

gsd-pi is a capable coding agent, but it does not know Marcus's rules by default. This skill constructs a gsd task that:

• Injects Marcus's coding constraints into the task description
• Defines a consistent handoff format (what Claude Code sends to gsd)
• Defines a consistent result format (what Claude Code reads back from gsd)
• Broadcasts lifecycle events to AgenticOS
• Handles gsd failures without silently swallowing errors

Prerequisites

# Verify gsd-pi is installed
gsd --version
# Expected: gsd-pi 2.x.x or higher

If gsd is not installed: npm install -g gsd-pi@latest

Marcus's Constraint Bundle

Every gsd task generated by this skill includes this constraint block verbatim:

## Constraints (non-negotiable)
- No em-dashes in any text output, comments, or commit messages. Use commas, colons, or parentheses instead.
- No "Co-Authored-By: Claude" or similar AI attribution in commit messages.
- Event-driven architecture only. No polling loops (no setInterval for state checks, no busy-wait).
- Dependency injection over direct instantiation. No "new ConcreteClass()" in business logic.
- Observer pattern for cross-module communication. Singleton with re-entrancy guard for shared observers.
- No hardcoded configuration values. Environment variables or config files for all settings.
- Commit working state with descriptive message explaining WHAT and WHY, not just "fixed stuff".
- Zero tolerance for TypeScript errors or ESLint errors before committing.

Handoff Format

Sending a Task to gsd

Construct the task file at .gsd-task.md in the project root:

# GSD Task: <task-title>

## Objective
<one-sentence goal>

## Context
- Project: <project name and path>
- Branch: <current git branch>
- Stack: <tech stack>
- Relevant files: <list key files gsd should read>

## Acceptance Criteria
<numbered list of specific, verifiable outcomes>

## Constraints (non-negotiable)
[INSERT MARCUS CONSTRAINT BUNDLE VERBATIM]

## Out of Scope
<explicit list of what gsd should NOT change>

Then invoke gsd:

gsd run .gsd-task.md

Reading Results Back

After gsd completes, check these outputs in order:

1. Exit code: 0 = success, non-zero = failure. Never treat non-zero as success.
2. Git diff: git diff --stat shows what gsd changed. Review before accepting.
3. Build verification: Run the project's build command to confirm gsd's output compiles.
4. Test suite: Run npm test (or equivalent) to confirm no regressions.

If any check fails, do NOT commit gsd's changes. Report the failure with the specific check that failed and the full error output.

Execution Flow

Step 1: Prepare

Read the task description (from argument or context). Identify:

• Target project and branch
• Specific files in scope
• Acceptance criteria (what done looks like)
• Files explicitly out of scope (gsd should not touch these)

Step 2: Construct Task File

Write .gsd-task.md with full context. The more specific the acceptance criteria, the better gsd's output quality. Vague criteria produce vague code.

If --dry-run flag is set: print the task file content and stop. Do not invoke gsd.

Step 3: Invoke gsd

gsd run .gsd-task.md 2>&1 | tee .gsd-output.log

Capture stdout and stderr together. If gsd exits non-zero, surface the full log.

Step 4: Validate Output

Run all four checks (exit code, git diff review, build, tests). If all pass, stage and commit gsd's changes:

git add -p  # Interactive staging -- review each hunk
git commit -m "<type>(<scope>): <description>"

Never use git add -A or git add . after a gsd run -- review hunks individually.

Step 5: Broadcast Result

from scripts.agenticos_push import push_event, EventType
push_event(EventType.PHASE_COMPLETE, workflow_id="gsd-driver", extra={
    "task": task_title,
    "result": "success" | "failure",
    "files_changed": changed_file_count
})

Fire-and-forget. Never block on this.

Step 6: Clean Up

rm .gsd-task.md .gsd-output.log

Do not leave task files in the working tree. They contain project context that should not be committed.

Error Handling

Failure	Response
gsd not installed	Instruct user to run npm install -g gsd-pi@latest, stop
gsd exits non-zero	Surface full .gsd-output.log, do not commit anything
Build fails after gsd	Show build errors, suggest git checkout -- . to revert
Tests fail after gsd	Show failing tests, do not commit, report to user
Constraint violation found in diff	Block commit, list violations with line numbers

Constraint Violation Check

Before committing any gsd output, scan the diff for constraint violations:

# Check for em-dashes in changed files
git diff --cached | grep -E "(—|--[^>])" | grep "^+" 

# Check for Co-Authored-By
git diff --cached | grep -i "co-authored" | grep "^+"

# Check for polling patterns
git diff --cached | grep -E "setInterval|while.*poll|busy.?wait" | grep "^+"

If any violations are found, block the commit and report them with file + line number.

Integration with autonomous-workflow

When autonomous-workflow reaches the execution phase and the task is suitable for gsd:

1. autonomous-workflow writes the task spec to state/gsd-task-<phase>.md
2. This skill reads that file and runs the execution flow above
3. On success, returns control to autonomous-workflow with the validated result
4. autonomous-workflow marks the phase complete and advances

The interface contract: autonomous-workflow provides a spec file path as the argument. gsd-driver returns exit 0 on success, exit 1 on any validation failure.

Cross-References

• ai-agents/gsd-workflow: The handoff contract specification (read this first for integration design)
• ai-agents/autonomous-workflow: The orchestrator that invokes gsd-driver for execution phases
• _core/universal-coding-standards: The source of truth for Marcus's coding constraints