Feature Request: GSD (Get Shit Done) Integration for Existing Projects

[simfor99]

Problem

Currently, Autocoder requires a manually written app_spec.txt to initialize features. For existing projects that were started with other tools (Claude Code, Cursor, etc.), there's no easy way to onboard them to Autocoder.

Users have to manually analyze their codebase and write the XML spec from scratch - which is time-consuming and error-prone.

Proposed Solution

Integrate with the Get Shit Done (GSD) Framework to automatically generate app_spec.txt from existing codebases.

How It Works

Existing Project
       │
       ▼
/gsd:map-codebase          ← Analyzes codebase with 4 parallel agents
       │
       ▼
.planning/codebase/
├── STACK.md               ← Technologies, frameworks, dependencies
├── ARCHITECTURE.md        ← Patterns, layers, data flow
├── STRUCTURE.md           ← Directory layout, key files
├── CONVENTIONS.md         ← Code style, naming patterns
├── INTEGRATIONS.md        ← External APIs, services
├── TESTING.md             ← Test structure
└── CONCERNS.md            ← Technical debt
       │
       ▼
/gsd:to-autocoder-spec     ← NEW: Converts GSD output to Autocoder format
       │
       ▼
prompts/app_spec.txt       ← Generated XML spec for Autocoder
       │
       ▼
Autocoder Initializer      ← Creates features.db from spec
       │
       ▼
Coding Agent               ← Implements features autonomously

Mapping GSD Documents to Autocoder Spec

GSD Document	Autocoder Section
STACK.md Languages	<technology_stack>
STACK.md Frameworks	<frontend>, <backend>
STACK.md Dependencies	<prerequisites>
ARCHITECTURE.md Layers	<core_features> categories
ARCHITECTURE.md Data Flow	<key_interactions>
STRUCTURE.md Layout	<ui_layout>, <implementation_steps>
INTEGRATIONS.md APIs	<api_endpoints_summary>

Benefits

1. Zero manual spec writing - Codebase analysis generates the spec automatically
2. Respects existing patterns - Features align with actual code architecture
3. Token efficient - One-time conversion, not repeated context loading
4. Framework agnostic - Works with any tech stack GSD can analyze

Implementation Options

Option A: External Skill (Already Built)

I've created a Claude Code skill that bridges GSD and Autocoder:

~/.claude/skills/gsd-to-autocoder-spec/
├── SKILL.md                        # Workflow definition
└── references/
    └── app-spec-format.md          # XML format reference

Usage:

cd /path/to/existing-project
# Run in Claude Code:
/gsd:map-codebase
/gsd:to-autocoder-spec
# Then start Autocoder normally

Option B: Native Integration

Add GSD support directly to Autocoder:

1. Detect GSD mapping in prompts.py:

def get_app_spec(project_dir: Path) -> str:
    # Check for GSD mapping first
    gsd_dir = project_dir / ".planning" / "codebase"
    if gsd_dir.exists() and not (project_dir / "prompts" / "app_spec.txt").exists():
        return generate_spec_from_gsd(gsd_dir)
    # ... existing logic

2. Auto-generate spec from GSD documents
3. Skip manual spec creation if GSD mapping exists

Option C: Prompt Enhancement

Modify coding_prompt.template.md to read GSD context:

# If GSD mapping exists, read it for context
if [ -d ".planning/codebase" ]; then
  cat .planning/codebase/STACK.md
  cat .planning/codebase/ARCHITECTURE.md
fi

Why GSD?

GSD's /gsd:map-codebase spawns 4 parallel Explore agents that thoroughly analyze:

• Technology stack and dependencies
• Architecture patterns and code organization
• Directory structure and conventions
• Technical debt and concerns

This produces comprehensive, structured documentation that maps perfectly to Autocoder's spec format.

Related

• GSD Framework: https://github.com/glittercowboy/get-shit-done
• GSD map-codebase workflow: Creates .planning/codebase/*.md
• Autocoder app_spec format: XML with <project_specification> root

---

Note: I'm happy to contribute the skill code or help with native integration. The skill is already working in my local setup.

[simfor99]

Skill Implementation Details

Here's the complete skill code that bridges GSD and Autocoder:

SKILL.md

---
name: gsd-to-autocoder-spec
description: |
  Convert GSD codebase mapping to Autocoder app_spec.txt. This skill should be used when
  the user has run /gsd:map-codebase and wants to use Autocoder on an existing project.
  Triggers: "convert to autocoder", "gsd to spec", "create app_spec from codebase",
  "use autocoder on existing project", after /gsd:map-codebase completion.
---

# GSD to Autocoder Spec Converter

Converts `.planning/codebase/*.md` (GSD mapping output) to `prompts/app_spec.txt` (Autocoder format).

## When to Use

- After running `/gsd:map-codebase` on an existing project
- When onboarding an existing codebase to Autocoder
- User wants Autocoder to continue development on existing code

## Prerequisites

The project must have `.planning/codebase/` with these files:
- `STACK.md` - Technology stack (required)
- `ARCHITECTURE.md` - Code architecture (required)
- `STRUCTURE.md` - Directory layout (required)
- `CONVENTIONS.md` - Code conventions (optional)
- `INTEGRATIONS.md` - External services (optional)

## Process

### Step 1: Verify GSD Mapping Exists

\`\`\`bash
ls -la .planning/codebase/
\`\`\`

**Required files:** STACK.md, ARCHITECTURE.md, STRUCTURE.md

If `.planning/codebase/` doesn't exist, prompt user to run `/gsd:map-codebase` first.

### Step 2: Read Codebase Documentation

\`\`\`bash
cat .planning/codebase/STACK.md
cat .planning/codebase/ARCHITECTURE.md
cat .planning/codebase/STRUCTURE.md
cat .planning/codebase/CONVENTIONS.md 2>/dev/null || true
cat .planning/codebase/INTEGRATIONS.md 2>/dev/null || true
\`\`\`

Extract key information:
- **From STACK.md:** Languages, frameworks, dependencies, runtime, ports
- **From ARCHITECTURE.md:** Patterns, layers, data flow, entry points
- **From STRUCTURE.md:** Directory layout, key file locations, naming conventions
- **From INTEGRATIONS.md:** External APIs, services, databases

### Step 3: Extract Project Metadata

\`\`\`bash
cat package.json 2>/dev/null | head -20 || echo "No package.json"
\`\`\`

### Step 4: Generate app_spec.txt

Create `prompts/` directory and generate XML spec:

\`\`\`bash
mkdir -p prompts
\`\`\`

**Mapping GSD Documents to Autocoder Spec:**

| GSD Source | Autocoder Target |
|------------|------------------|
| STACK.md Languages | `<technology_stack>` |
| STACK.md Frameworks | `<frontend>`, `<backend>` |
| STACK.md Dependencies | `<prerequisites>` |
| ARCHITECTURE.md Layers | `<core_features>` categories |
| ARCHITECTURE.md Data Flow | `<key_interactions>` |
| ARCHITECTURE.md Entry Points | `<implementation_steps>` |
| STRUCTURE.md Layout | `<ui_layout>` (if frontend) |
| INTEGRATIONS.md APIs | `<api_endpoints_summary>` |

**Feature Generation Guidelines:**

1. Analyze existing code structure to infer implemented features
2. Each feature must be testable: "User can...", "System displays...", "API returns..."
3. Group features by category matching architecture layers
4. Target feature counts by complexity:
   - Simple CLI/utility: ~100-150 features
   - Medium web app: ~200-250 features
   - Complex full-stack: ~300-400 features

### Step 5: Verify Generated Spec

\`\`\`bash
head -100 prompts/app_spec.txt
grep -c "User can\|System\|API\|Feature" prompts/app_spec.txt || echo "0"
\`\`\`

### Step 6: Report Completion

\`\`\`
app_spec.txt generated from GSD codebase mapping.

Source: .planning/codebase/*.md
Output: prompts/app_spec.txt

Next: Start Autocoder
  python ~/projects/autocoder/start.py
\`\`\`

---

Directory Structure

~/.claude/skills/gsd-to-autocoder-spec/
├── SKILL.md                        # Main workflow (above)
└── references/
    └── app-spec-format.md          # Complete XML format reference

The references/app-spec-format.md contains the full XML schema documentation for app_spec.txt including all sections (<project_specification>, <technology_stack>, <core_features>, etc.).

---

Usage Example

# 1. Navigate to existing project
cd /path/to/my-existing-app

# 2. Run GSD codebase mapping (in Claude Code)
/gsd:map-codebase
# → Creates .planning/codebase/*.md

# 3. Convert to Autocoder spec
/gsd:to-autocoder-spec
# → Creates prompts/app_spec.txt

# 4. Start Autocoder
python ~/projects/autocoder/start.py
# → Select project
# → Initializer creates features.db from spec
# → Coding agent begins autonomous development

This skill is designed to be framework-agnostic and works with any project that GSD can analyze.

[simfor99]

Update: Brownfield Mode Added (v2.0)

The gsd-to-autocoder-spec skill has been extended with Brownfield support for existing projects with bugs that need fixing.

New Capabilities

Feature	Description
Bug Detection	Scans codebase for TODO/FIXME/BUG comments
Code Health Analysis	Classifies modules as working, buggy, or deprecated
Fix Features	Generates <features_to_fix> with highest priority
Code Preservation	Marks working modules as read-only

Extended Flow

Existing Project (with bugs)
       │
       ▼
/gsd:map-codebase
       │
       ▼
/gsd:to-autocoder-spec
       │
       ├─ "Greenfield?" → Standard spec (existing behavior)
       │
       └─ "Brownfield?" → Extended spec with:
              │
              ├── <brownfield_config>     ← Mode + source project
              ├── <existing_code>         ← Modules with status
              ├── <features_to_fix>       ← Bug fixes (priority 1-N)
              └── <core_features>         ← New features (lower priority)

Bug Detection Scans

# What the skill scans for:
grep -rn "TODO\|FIXME\|BUG\|HACK\|XXX" --include="*.ts" --include="*.tsx"
grep -rn "catch.*{}" --include="*.ts"  # Empty catch blocks
grep -rn "not implemented" --include="*.ts"  # Stubs

New XML Sections

Brownfield Config:

<brownfield_config>
  <mode>brownfield</mode>
  <source_project>/absolute/path/to/project</source_project>
  <import_strategy>selective</import_strategy>
</brownfield_config>

Existing Code (with health status):

<existing_code>
  <module name="scraper" status="working">
    <source_path>lib/scraper/</source_path>
    <action>copy</action>
  </module>
  <module name="entity-extraction" status="buggy">
    <source_path>services/entityExtraction/</source_path>
    <action>fix</action>
    <known_issues>
      - Timeout on large documents
      - Memory leak in batch processing
    </known_issues>
  </module>
</existing_code>

Features to Fix (highest priority):

<features_to_fix>
  <fix id="FIX-001" priority="critical" category="functional">
    <title>Entity extraction timeout on large documents</title>
    <symptom>Processing documents > 10KB causes 30s timeout</symptom>
    <location>services/entityExtraction/extractEntities.ts:45-89</location>
    <expected_behavior>Should complete in < 5s for documents up to 100KB</expected_behavior>
  </fix>
</features_to_fix>

Agent Behavior in Brownfield Mode

Initializer Agent:

1. Detects <brownfield_config> in spec
2. Imports existing code from source project
3. Creates FIX features with priority 1-N
4. Creates regular features with lower priority

Coding Agent:

1. Checks IMPORTED_CODE.md before modifying files
2. Never overwrites modules with status="working"
3. Makes targeted fixes at specified locations
4. Tests specific symptoms are resolved

Use Cases

Scenario	Mode	Result
New project from scratch	Greenfield	Standard Autocoder behavior
Existing project, add features	Greenfield	Features derived from code analysis
Existing project with bugs	Brownfield	Fixes bugs first, then adds features
Migration to new architecture	Brownfield	Preserves working code, rebuilds broken parts

---

The skill is available at ~/.claude/skills/gsd-to-autocoder-spec/ and has been tested with complex full-stack applications.

[simfor99]

Update: Auto-Registration Added

Fixed a UX issue where generated projects didn't appear in Autocoder UI.

Problem

After running /gsd:to-autocoder-spec, the project had a valid app_spec.txt but wasn't visible in Autocoder because it wasn't registered in the project registry.

Solution

Added Step 5.5: Register Project in Autocoder Registry to the skill.

# Now runs automatically after spec generation:
PROJECT_NAME=$(basename "$(pwd)")
PROJECT_PATH=$(pwd)

cd ~/projects/autocoder && source venv/bin/activate && python -c "
from registry import register_project
from pathlib import Path
register_project('$PROJECT_NAME', Path('$PROJECT_PATH'))
"

Updated Flow

/gsd:to-autocoder-spec
       │
       ├── Generate app_spec.txt     ✓
       ├── Register in Autocoder     ✓  ← NEW
       └── Ready to use in UI        ✓

Now projects appear immediately in Autocoder UI after conversion - no manual registration needed.

[simfor99]

Update: Existing Spec Detection

Added Step 0 that checks for existing app_spec.txt before processing.

New Flow

/gsd:to-autocoder-spec
       │
       ▼
┌─ app_spec.txt exists? ─┐
│                        │
▼ YES                    ▼ NO
                         
"Option A or B?"         Continue normally
│                        
├─ A: Register Only      
│  → Skip to registry    
│  → Keep existing spec  
│                        
└─ B: Regenerate         
   → Delete old spec     
   → Create new from GSD 

Why This Matters

• Prevents accidental overwrite of manually crafted specs
• Allows re-running skill just to fix missing registry entry
• Gives user control over spec regeneration