golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: remove CONTRIBUTING.md and GSD-STYLE.md

Browse Source 
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-02-07 22:26:14 -06:00
parent e92e64ce48
commit 3f5ab10713
2 changed files with 0 additions and 844 deletions
Download Patch File Download Diff File Expand all files Collapse all files

331
CONTRIBUTING.md
View File

@@ -1,331 +0,0 @@
# Contributing to Get Shit Done
No enterprise theater. Ship useful code.
---
## Philosophy
GSD optimizes for **solo developer + Claude workflow**. The release process follows the same principle: complexity lives in automation, not your workflow.
**What this means:**
- No sprint ceremonies or release committees
- No multi-week stabilization branches
- Checkpoints before risky changes, not bureaucratic gates
- Ship when ready, batch when sensible
---
## Branch Strategy
Two branches. That's it.
```
main ════════════════════════════════════════════►
▲ ▲ ▲ ▲
│ │ │ │
v1.9.0 v1.9.1 v1.10.0 v2.0.0
│ │ │
hotfix batched minor
fixes features
```
### `main`
Production. Always installable via `npx get-shit-done-cc`.
| Rule | Why |
|------|-----|
| No direct commits | Forces checkpoint thinking |
| PRs required | Creates revert points |
| Must pass CI | Catches Windows/path issues |
### Feature Work
Branch → PR → Merge. No `develop` branch. No release branches.
```bash
# Start work
git checkout -b feat/model-profiles
# or fix/windows-paths
# or docs/checkpoint-examples
# Ship it
git push origin feat/model-profiles
# Open PR, get review, merge
```
**Branch naming:**
- `feat/description` — New capability
- `fix/description` — Bug fix
- `docs/description` — Documentation only
- `refactor/description` — Internal changes, no behavior change
- `hotfix/version-description` — Emergency production fix
---
## When to Branch vs. Direct Commit
**Use a branch when:**
- Adding new commands or workflows
- Changing core behavior (orchestrator, context loading)
- Touching multiple files
- You'd want a clean revert point
**Direct commit to main (maintainers only):**
- Typo fixes
- README updates
- Single-line bug fixes with obvious correctness
---
## Commits
Use conventional commits. Claude already does this.
```
feat(checkpoints): add rollback capability
fix(install): use absolute paths on Windows (#207)
docs(readme): update installation instructions
refactor(orchestrator): extract context loading
chore: remove old planning files
revert: remove codebase intelligence system
```
**Format:** `type(scope): description`
| Type | Use |
|------|-----|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation |
| `refactor` | Code change without behavior change |
| `chore` | Maintenance, dependencies |
| `revert` | Undoing previous commit |
---
## Releases & Tags
### Tag Sparingly
**Current problem:** 131 tags in one month. Too noisy.
**New rule:** Tag stable milestones, not every commit.
| Change Type | Tag? | Version Bump |
|-------------|------|--------------|
| Breaking change | Yes | MAJOR (2.0.0) |
| New feature | Yes | MINOR (1.10.0) |
| Bug fix | Batch | PATCH (1.9.x) |
| Documentation | No | — |
| Refactor | No | — |
### Version Cadence
- **Minor releases (1.X.0):** When features are ready. No fixed schedule.
- **Patch releases (1.9.X):** Batch fixes weekly, or immediately for critical bugs.
- **Major releases (X.0.0):** Breaking changes only. Rare.
### Pre-release Tags for Risky Features
The codebase intelligence system added 3,065 lines and a 21MB dependency. It got reverted. Pre-release tags prevent this:
```bash
# Experimental feature
git tag -a v1.10.0-alpha.1 -m "Alpha: experimental codebase intelligence"
# After testing
git tag -a v1.10.0-beta.1 -m "Beta: codebase intelligence stabilized"
# Ready for production
git tag -a v1.10.0 -m "Release: codebase intelligence"
```
Users opt-in: `npm install get-shit-done-cc@1.10.0-alpha.1`
**If it doesn't work out:** Delete pre-release tags, no messy public revert on main.
### Creating a Release
```bash
# Update version
npm version minor # or patch, or major
# Update CHANGELOG.md (already follows Keep a Changelog format)
# Commit
git add package.json CHANGELOG.md
git commit -m "chore: release v1.10.0"
# Tag
git tag -a v1.10.0 -m "Release v1.10.0"
git push origin main --tags
# Publish
npm publish
```
### GitHub Releases
Create formal releases for minor+ versions. Copy the CHANGELOG section.
```
Go to: github.com/glittercowboy/get-shit-done/releases/new
Select tag: v1.10.0
Title: v1.10.0
Description: [paste from CHANGELOG.md]
```
---
## Large Changes
If a feature touches >500 lines or adds dependencies, use a branch and PR. This creates a review point before the change lands on main.
---
## Hotfixes
Production broken? Skip the normal flow.
```bash
# Branch from main
git checkout main
git checkout -b hotfix/1.9.4-windows-crash
# Fix it
# ... make changes ...
# Ship immediately
git commit -m "fix(install): handle Windows UNC paths"
git push origin hotfix/1.9.4-windows-crash
# PR → merge → tag
npm version patch
git tag -a v1.9.5 -m "Hotfix: Windows UNC paths"
git push origin main --tags
npm publish
```
---
## Pull Request Guidelines
### Title
Use conventional commit format:
```
feat(checkpoints): add rollback capability
fix(install): use absolute paths on Windows
```
### Description
```markdown
## What
[One sentence: what does this PR do?]
## Why
[One sentence: why is this change needed?]
## Testing
[How did you verify it works?]
## Breaking Changes
[List any, or "None"]
```
### Review Checklist
- [ ] Follows GSD style (no enterprise patterns, no filler)
- [ ] Updates CHANGELOG.md for user-facing changes
- [ ] Doesn't add unnecessary dependencies
- [ ] Works on Windows (test paths with backslashes)
---
## What NOT to Do
Borrowed from GSD-STYLE.md:
**Enterprise Patterns (Banned):**
- Story points
- Sprint ceremonies
- RACI matrices
- Release committees
- Multi-week stabilization branches
- Change advisory boards
**Temporal Language (Banned in Code/Docs):**
- "We changed X to Y"
- "Previously"
- "No longer"
- "Instead of"
Exception: CHANGELOG.md, MIGRATION.md, git commits
**Vague Contributions (Banned):**
```
# BAD
"Improve performance"
"Fix bugs"
"Update documentation"
# GOOD
"Reduce orchestrator context load from 12KB to 4KB"
"Fix Windows path handling in hook commands (#207)"
"Add checkpoint rollback examples to README"
```
---
## Quick Reference
| I want to... | Do this |
|--------------|---------|
| Add a feature | Branch `feat/x` → PR → merge |
| Fix a bug | Branch `fix/x` → PR → merge |
| Fix production NOW | Branch `hotfix/version-x` → PR → merge → tag |
| Release features | `npm version minor` → tag → publish |
| Release fixes | Batch weekly, or `npm version patch` for critical |
| Try experimental feature | Tag as `v1.X.0-alpha.1` |
| Revert a mistake | `git revert` → PR → merge |
---
## Setting Up Development
```bash
# Clone
git clone https://github.com/glittercowboy/get-shit-done.git
cd get-shit-done
# Install
npm install
# Test locally
npm link
npx get-shit-done-cc
# Run tests
npm test
```
---
## Getting Help
- **Issues:** Bug reports, feature requests
- **Discussions:** Questions, ideas, show & tell
- **Discord:** [Link if exists]
---
*"The complexity is in the system, not in your workflow."*
— TÂCHES

513
GSD-STYLE.md
View File

@@ -1,513 +0,0 @@
# GSD-STYLE.md
> **Comprehensive reference.** Core rules auto-load from `.claude/rules/`. This document provides deep explanations and examples for when you need the full picture.
This document explains how GSD is written so future Claude instances can contribute consistently.
## Core Philosophy
GSD is a **meta-prompting system** where every file is both implementation and specification. Files teach Claude how to build software systematically. The system optimizes for:
- **Solo developer + Claude workflow** (no enterprise patterns)
- **Context engineering** (manage Claude's context window deliberately)
- **Plans as prompts** (PLAN.md files are executable, not documents to transform)
---
## File Structure Conventions
### Slash Commands (`commands/gsd/*.md`)
```yaml
---
name: gsd:command-name
description: One-line description
argument-hint: "<required>" or "[optional]"
allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
---
```
**Section order:**
1. `<objective>` — What/why/when (always present)
2. `<execution_context>` — @-references to workflows, templates, references
3. `<context>` — Dynamic content: `$ARGUMENTS`, bash output, @file refs
4. `<process>` or `<step>` elements — Implementation steps
5. `<success_criteria>` — Measurable completion checklist
**Commands are thin wrappers.** Delegate detailed logic to workflows.
### Workflows (`get-shit-done/workflows/*.md`)
No YAML frontmatter. Structure varies by workflow.
**Common tags** (not all workflows use all of these):
- `<purpose>` — What this workflow accomplishes
- `<when_to_use>` or `<trigger>` — Decision criteria
- `<required_reading>` — Prerequisite files
- `<process>` — Container for steps
- `<step>` — Individual execution step
Some workflows use domain-specific tags like `<philosophy>`, `<references>`, `<planning_principles>`, `<decimal_phase_numbering>`.
**When using `<step>` elements:**
- `name` attribute: snake_case (e.g., `name="load_project_state"`)
- `priority` attribute: Optional ("first", "second")
**Key principle:** Match the style of the specific workflow you're editing.
### Templates (`get-shit-done/templates/*.md`)
Structure varies. Common patterns:
- Most start with `# [Name] Template` header
- Many include a `<template>` block with the actual template content
- Some include examples or guidelines sections
**Placeholder conventions:**
- Square brackets: `[Project Name]`, `[Description]`
- Curly braces: `{phase}-{plan}-PLAN.md`
### References (`get-shit-done/references/*.md`)
Typically use outer XML containers related to filename, but structure varies.
Examples:
- `principles.md` → `<principles>...</principles>`
- `checkpoints.md` → `<overview>` then `<checkpoint_types>`
- `plan-format.md` → `<overview>` then `<core_principle>`
Internal organization varies — semantic sub-containers, markdown headers within XML, code examples.
---
## XML Tag Conventions
### Semantic Containers Only
XML tags serve semantic purposes. Use Markdown headers for hierarchy within.
**DO:**
```xml
<objective>
## Primary Goal
Build authentication system
## Success Criteria
- Users can log in
- Sessions persist
</objective>
```
**DON'T:**
```xml
<section name="objective">
<subsection name="primary-goal">
<content>Build authentication system</content>
</subsection>
</section>
```
### Task Structure
```xml
<task type="auto">
<name>Task N: Action-oriented name</name>
<files>src/path/file.ts, src/other/file.ts</files>
<action>What to do, what to avoid and WHY</action>
<verify>Command or check to prove completion</verify>
<done>Measurable acceptance criteria</done>
</task>
```
**Task types:**
- `type="auto"` — Claude executes autonomously
- `type="checkpoint:human-verify"` — User must verify
- `type="checkpoint:decision"` — User must choose
### Checkpoint Structure
```xml
<task type="checkpoint:human-verify" gate="blocking">
<what-built>Description of what was built</what-built>
<how-to-verify>Numbered steps for user</how-to-verify>
<resume-signal>Text telling user how to continue</resume-signal>
</task>
<task type="checkpoint:decision" gate="blocking">
<decision>What needs deciding</decision>
<context>Why this matters</context>
<options>
<option id="identifier">
<name>Option Name</name>
<pros>Benefits</pros>
<cons>Tradeoffs</cons>
</option>
</options>
<resume-signal>Selection instruction</resume-signal>
</task>
```
### Conditional Logic
```xml
<if mode="yolo">
Content for yolo mode
</if>
<if mode="interactive" OR="custom with gates.execute_next_plan true">
Content for multiple conditions
</if>
```
---
## @-Reference Patterns
**Static references** (always load):
```
@~/.claude/get-shit-done/workflows/execute-phase.md
@.planning/PROJECT.md
```
**Conditional references** (based on existence):
```
@.planning/DISCOVERY.md (if exists)
```
**@-references are lazy loading signals.** They tell Claude what to read, not pre-loaded content.
---
## Naming Conventions
| Type | Convention | Example |
|------|------------|---------|
| Files | kebab-case | `execute-phase.md` |
| Commands | `gsd:kebab-case` | `gsd:execute-phase` |
| XML tags | kebab-case | `<execution_context>` |
| Step names | snake_case | `name="load_project_state"` |
| Bash variables | CAPS_UNDERSCORES | `PHASE_ARG`, `PLAN_START_TIME` |
| Type attributes | colon separator | `type="checkpoint:human-verify"` |
---
## Language & Tone
### Imperative Voice
**DO:** "Execute tasks", "Create file", "Read STATE.md"
**DON'T:** "Execution is performed", "The file should be created"
### No Filler
Absent: "Let me", "Just", "Simply", "Basically", "I'd be happy to"
Present: Direct instructions, technical precision
### No Sycophancy
Absent: "Great!", "Awesome!", "Excellent!", "I'd love to help"
Present: Factual statements, verification results, direct answers
### Brevity with Substance
**Good one-liner:** "JWT auth with refresh rotation using jose library"
**Bad one-liner:** "Phase complete" or "Authentication implemented"
### Character Preservation
**ALWAYS preserve diacritics and special characters in text content.**
- ą, ę, ć, ź, ż, ó, ł, ń, ś (Polish)
- ü, ö, ä, ß (German)
- é, è, ê, ç (French)
- and all other language-specific characters
**User's typing style ≠ output style.**
---
## Context Engineering
### Size Constraints
- **Plans:** 2-3 tasks maximum
- **Quality curve:** 0-30% peak, 30-50% good, 50-70% degrading, 70%+ poor
- **Split triggers:** >3 tasks, multiple subsystems, >5 files per task
### Fresh Context Pattern
Use subagents for autonomous work. Reserve main context for user interaction.
### State Preservation
- `STATE.md` — Living memory across sessions
- `agent-history.json` — Subagent tracking for resume
- SUMMARY.md frontmatter — Machine-readable for dependency graphs
---
## Anti-Patterns to Avoid
### Enterprise Patterns (Banned)
- Story points, sprint ceremonies, RACI matrices
- Human dev time estimates (days/weeks)
- Team coordination, knowledge transfer docs
- Change management processes
### Temporal Language (Banned in Implementation Docs)
**DON'T:** "We changed X to Y", "Previously", "No longer", "Instead of"
**DO:** Describe current state only
**Exception:** CHANGELOG.md, MIGRATION.md, git commits
### Generic XML (Banned)
**DON'T:** `<section>`, `<item>`, `<content>`
**DO:** Semantic purpose tags: `<objective>`, `<verification>`, `<action>`
### Vague Tasks (Banned)
```xml
<!-- BAD -->
<task type="auto">
<name>Add authentication</name>
<action>Implement auth</action>
<verify>???</verify>
</task>
<!-- GOOD -->
<task type="auto">
<name>Create login endpoint with JWT</name>
<files>src/app/api/auth/login/route.ts</files>
<action>POST endpoint accepting {email, password}. Query User by email, compare password with bcrypt. On match, create JWT with jose library, set as httpOnly cookie. Return 200. On mismatch, return 401.</action>
<verify>curl -X POST localhost:3000/api/auth/login returns 200 with Set-Cookie header</verify>
<done>Valid credentials → 200 + cookie. Invalid → 401.</done>
</task>
```
---
## Commit Conventions
### Format
```
{type}({phase}-{plan}): {description}
```
### Types
| Type | Use |
|------|-----|
| `feat` | New feature |
| `fix` | Bug fix |
| `test` | Tests only (TDD RED) |
| `refactor` | Code cleanup (TDD REFACTOR) |
| `docs` | Documentation/metadata |
| `chore` | Config/dependencies |
### Rules
- One commit per task during execution
- Stage files individually (never `git add .`)
- Capture hash for SUMMARY.md
- Include Co-Authored-By line
---
## UX Patterns
**Visual patterns:** `get-shit-done/references/ui-brand.md`
Orchestrators @-reference ui-brand.md for stage banners, checkpoint boxes, status symbols, and completion displays.
### "Next Up" Format
```markdown
───────────────────────────────────────────────────────────────
## ▶ Next Up
**{identifier}: {name}** — {one-line description}
`{copy-paste command}`
<sub>`/clear` first → fresh context window</sub>
───────────────────────────────────────────────────────────────
**Also available:**
- Alternative option
- Another option
───────────────────────────────────────────────────────────────
```
### Decision Gates
Always use AskUserQuestion with concrete options. Never plain text prompts.
Include escape hatch: "Something else", "Let me describe"
---
## Progressive Disclosure
Information flows through layers:
1. **Command** — High-level objective, delegates to workflow
2. **Workflow** — Detailed process, references templates/references
3. **Template** — Concrete structure with placeholders
4. **Reference** — Deep dive on specific concept
Each layer answers different questions:
- Command: "Should I use this?"
- Workflow: "What happens?"
- Template: "What does output look like?"
- Reference: "Why this design?"
---
## Depth & Compression
Depth setting controls compression tolerance:
- **Quick:** Compress aggressively (1-3 plans/phase)
- **Standard:** Balanced (3-5 plans/phase)
- **Comprehensive:** Resist compression (5-10 plans/phase)
**Key principle:** Depth controls compression, not inflation. Never pad to hit a target number. Derive plans from actual work.
---
## Quick Mode Patterns
Quick mode provides GSD guarantees for ad-hoc tasks without full planning overhead.
### When to Use Quick Mode
**Quick mode:**
- Task is small and self-contained
- You know exactly what to do (no research needed)
- Task doesn't warrant full phase planning
- Mid-project fixes or small additions
**Full planning:**
- Task involves multiple subsystems
- You need to investigate approach first
- Task is part of a larger phase
- Task might have hidden complexity
### Quick Task Structure
```
.planning/quick/
├── 001-add-dark-mode/
│ ├── PLAN.md
│ └── SUMMARY.md
├── 002-fix-login-bug/
│ ├── PLAN.md
│ └── SUMMARY.md
```
Numbering: 3-digit sequential (001, 002, 003...)
Slug: kebab-case from description, max 40 chars
### Quick Mode Tracking
Quick tasks update STATE.md, NOT ROADMAP.md:
```markdown
### Quick Tasks Completed
| # | Description | Date | Commit | Directory |
|---|-------------|------|--------|-----------|
| 001 | Add dark mode toggle | 2026-01-19 | abc123f | [001-add-dark-mode](./quick/001-add-dark-mode/) |
```
### Quick Mode Orchestration
Unlike full phases, quick mode orchestration is inline in the command file — no separate workflow. The simplified flow:
1. Validate ROADMAP.md exists (project active)
2. Get task description
3. Spawn planner (quick constraints)
4. Spawn executor
5. Update STATE.md
6. Commit artifacts
### Commit Convention
```
docs(quick-NNN): description
Quick task completed.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
```
---
## TDD Plans
### Detection Heuristic
> Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
Yes → TDD plan (one feature per plan)
No → Standard plan
### TDD Plan Structure
```yaml
---
type: tdd
---
```
```xml
<objective>
Implement [feature] using TDD (RED → GREEN → REFACTOR)
</objective>
<behavior>
Expected behavior specification
</behavior>
<implementation>
How to make tests pass
</implementation>
```
### TDD Commits
- RED: `test({phase}-{plan}): add failing test for [feature]`
- GREEN: `feat({phase}-{plan}): implement [feature]`
- REFACTOR: `refactor({phase}-{plan}): clean up [feature]`
---
## Summary: Core Meta-Patterns
1. **XML for semantic structure, Markdown for content**
2. **@-references are lazy loading signals**
3. **Commands delegate to workflows**
4. **Progressive disclosure hierarchy**
5. **Imperative, brief, technical** — no filler, no sycophancy
6. **Solo developer + Claude** — no enterprise patterns
7. **Context size as quality constraint** — split aggressively
8. **Temporal language banned** — current state only
9. **Plans ARE prompts** — executable, not documents
10. **Atomic commits** — Git history as context source
11. **AskUserQuestion for all exploration** — always options
12. **Checkpoints post-automation** — automate first, verify after
13. **Deviation rules are automatic** — no permission for bugs/critical
14. **Depth controls compression** — derive from actual work
15. **TDD gets dedicated plans** — cycle too heavy to embed