feat: add GSD integration skill for existing projects

Add skill to convert GSD codebase mapping (.planning/codebase/*.md) to Autocoder app_spec.txt format. This enables onboarding existing projects to Autocoder without manually writing the XML spec. Workflow: 1. Run /gsd:map-codebase on existing project 2. Run /gsd-to-autocoder-spec to generate app_spec.txt 3. Start Autocoder normally Closes #55 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-30 06:12:06 +00:00 · 2026-01-13 21:00:57 +01:00
parent 07c2010d32
commit 29715f2136
3 changed files with 524 additions and 0 deletions
--- a/.claude/commands/gsd-to-autocoder-spec.md
+++ b/.claude/commands/gsd-to-autocoder-spec.md
@@ -0,0 +1,10 @@
+---
+allowed-tools: Read, Write, Bash, Glob, Grep
+description: Convert GSD codebase mapping to Autocoder app_spec.txt
+---
+
+# GSD to Autocoder Spec
+
+Convert `.planning/codebase/*.md` (from `/gsd:map-codebase`) to Autocoder's `prompts/app_spec.txt`.
+
+@.claude/skills/gsd-to-autocoder-spec/SKILL.md
--- a/.claude/skills/gsd-to-autocoder-spec/SKILL.md
+++ b/.claude/skills/gsd-to-autocoder-spec/SKILL.md
@@ -0,0 +1,221 @@
+---
+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 name="verify_input">
+### 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:
+```
+GSD codebase mapping not found.
+
+Run /gsd:map-codebase first to analyze the existing codebase.
+```
+Stop workflow.
+</step>
+
+<step name="read_codebase_docs">
+### Step 2: Read Codebase Documentation
+
+Read all available GSD documents:
+
+```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>
+
+<step name="read_package_json">
+### Step 3: Extract Project Metadata
+
+```bash
+cat package.json 2>/dev/null | head -20 || echo "No package.json"
+```
+
+Extract:
+- Project name
+- Version
+- Main dependencies
+</step>
+
+<step name="generate_spec">
+### Step 4: Generate app_spec.txt
+
+Create `prompts/` directory:
+```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>` |
+| INTEGRATIONS.md Services | `<prerequisites>` |
+
+**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
+
+**Write the spec file** using the XML format from [references/app-spec-format.md](references/app-spec-format.md):
+
+```bash
+cat > prompts/app_spec.txt << 'EOF'
+<project_specification>
+  <project_name>{from package.json or directory}</project_name>
+
+  <overview>
+    {Synthesized from ARCHITECTURE.md overview}
+  </overview>
+
+  <technology_stack>
+    <frontend>
+      <framework>{from STACK.md}</framework>
+      <styling>{from STACK.md}</styling>
+      <port>{from STACK.md or default 3000}</port>
+    </frontend>
+    <backend>
+      <runtime>{from STACK.md}</runtime>
+      <database>{from STACK.md or INTEGRATIONS.md}</database>
+      <port>{from STACK.md or default 3001}</port>
+    </backend>
+  </technology_stack>
+
+  <prerequisites>
+    <environment_setup>
+      {from STACK.md Runtime + INTEGRATIONS.md requirements}
+    </environment_setup>
+  </prerequisites>
+
+  <core_features>
+    <!-- Group by ARCHITECTURE.md layers -->
+    <{layer_name}>
+      - {Feature derived from code analysis}
+      - {Feature derived from code analysis}
+    </{layer_name}>
+  </core_features>
+
+  <api_endpoints_summary>
+    {from INTEGRATIONS.md or inferred from STRUCTURE.md routes/}
+  </api_endpoints_summary>
+
+  <key_interactions>
+    {from ARCHITECTURE.md Data Flow}
+  </key_interactions>
+
+  <success_criteria>
+    <functionality>
+      - All existing features continue working
+      - New features integrate seamlessly
+      - No regression in core functionality
+    </functionality>
+  </success_criteria>
+</project_specification>
+EOF
+```
+</step>
+
+<step name="verify_output">
+### Step 5: Verify Generated Spec
+
+```bash
+head -100 prompts/app_spec.txt
+echo "---"
+grep -c "User can\|System\|API\|Feature" prompts/app_spec.txt || echo "0"
+```
+
+**Validation checklist:**
+- [ ] `<project_specification>` root tag present
+- [ ] `<project_name>` matches actual project
+- [ ] `<technology_stack>` reflects STACK.md
+- [ ] `<core_features>` has categorized features
+- [ ] Features are specific and testable
+</step>
+
+<step name="completion">
+### Step 6: Report Completion
+
+Output:
+```
+app_spec.txt generated from GSD codebase mapping.
+
+Source: .planning/codebase/*.md
+Output: prompts/app_spec.txt
+
+Next: Start Autocoder
+
+  cd {project_dir}
+  python ~/projects/autocoder/start.py
+
+Or via UI:
+  ~/projects/autocoder/start_ui.sh
+
+The Initializer will create features.db from this spec.
+```
+</step>
+
+## XML Format Reference
+
+See [references/app-spec-format.md](references/app-spec-format.md) for complete XML structure with all sections.
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| No .planning/codebase/ | Run `/gsd:map-codebase` first |
+| Missing required files | Re-run GSD mapping |
+| Cannot infer features | Ask user for clarification |
--- a/.claude/skills/gsd-to-autocoder-spec/references/app-spec-format.md
+++ b/.claude/skills/gsd-to-autocoder-spec/references/app-spec-format.md
@@ -0,0 +1,293 @@
+# Autocoder app_spec.txt XML Format
+
+Complete reference for the XML structure expected by Autocoder's Initializer agent.
+
+## Root Structure
+
+```xml
+<project_specification>
+  <project_name>...</project_name>
+  <overview>...</overview>
+  <technology_stack>...</technology_stack>
+  <prerequisites>...</prerequisites>
+  <core_features>...</core_features>
+  <database_schema>...</database_schema>
+  <api_endpoints_summary>...</api_endpoints_summary>
+  <ui_layout>...</ui_layout>
+  <design_system>...</design_system>
+  <key_interactions>...</key_interactions>
+  <implementation_steps>...</implementation_steps>
+  <success_criteria>...</success_criteria>
+</project_specification>
+```
+
+## Section Details
+
+### project_name
+```xml
+<project_name>my-awesome-app</project_name>
+```
+Simple string, typically from package.json name field.
+
+### overview
+```xml
+<overview>
+  A brief 2-3 sentence description of what the project does,
+  what problem it solves, and who it's for.
+</overview>
+```
+
+### technology_stack
+```xml
+<technology_stack>
+  <frontend>
+    <framework>React with Vite</framework>
+    <styling>Tailwind CSS</styling>
+    <state_management>React hooks and context</state_management>
+    <routing>React Router</routing>
+    <port>3000</port>
+  </frontend>
+  <backend>
+    <runtime>Node.js with Express</runtime>
+    <database>SQLite with better-sqlite3</database>
+    <port>3001</port>
+  </backend>
+  <communication>
+    <api>RESTful endpoints</api>
+  </communication>
+</technology_stack>
+```
+
+### prerequisites
+```xml
+<prerequisites>
+  <environment_setup>
+    - Node.js 18+ installed
+    - npm or pnpm package manager
+    - Required API keys: OPENAI_API_KEY, etc.
+  </environment_setup>
+</prerequisites>
+```
+
+### core_features (CRITICAL)
+
+This is where features are defined. Each feature becomes a test case in features.db.
+
+```xml
+<core_features>
+  <authentication>
+    - User can register with email/password
+    - User can login and receive session token
+    - User can logout and invalidate session
+    - User can reset password via email link
+    - System redirects unauthenticated users to login
+  </authentication>
+
+  <dashboard>
+    - User can view summary statistics on dashboard
+    - Dashboard displays recent activity list
+    - User can click items to navigate to detail view
+    - Dashboard updates in real-time when data changes
+  </dashboard>
+
+  <data_management>
+    - User can create new items via form
+    - User can view list of items with pagination
+    - User can edit existing items
+    - User can delete items with confirmation dialog
+    - User can search items by keyword
+    - User can filter items by category
+    - User can sort items by date/name/status
+  </data_management>
+
+  <api_layer>
+    - API returns 401 for unauthenticated requests
+    - API returns 403 for unauthorized actions
+    - API validates input and returns 400 for invalid data
+    - API returns paginated results for list endpoints
+  </api_layer>
+
+  <user_interface>
+    - UI is responsive on mobile (375px width)
+    - UI is responsive on tablet (768px width)
+    - UI displays loading states during async operations
+    - UI shows toast notifications for actions
+    - UI handles errors gracefully with user feedback
+  </user_interface>
+</core_features>
+```
+
+**Feature Writing Rules:**
+1. Start with action verb: "User can...", "System displays...", "API returns..."
+2. Be specific and testable
+3. One behavior per feature
+4. Group by functional area
+
+### database_schema
+```xml
+<database_schema>
+  <tables>
+    <users>
+      - id (PRIMARY KEY)
+      - email (UNIQUE, NOT NULL)
+      - password_hash (NOT NULL)
+      - name
+      - created_at, updated_at
+    </users>
+    <items>
+      - id (PRIMARY KEY)
+      - user_id (FOREIGN KEY -> users.id)
+      - title (NOT NULL)
+      - description
+      - status (enum: draft, active, archived)
+      - created_at, updated_at
+    </items>
+  </tables>
+</database_schema>
+```
+
+### api_endpoints_summary
+```xml
+<api_endpoints_summary>
+  <authentication>
+    - POST /api/auth/register
+    - POST /api/auth/login
+    - POST /api/auth/logout
+    - GET /api/auth/me
+  </authentication>
+  <items>
+    - GET /api/items (list with pagination)
+    - POST /api/items (create)
+    - GET /api/items/:id (get single)
+    - PUT /api/items/:id (update)
+    - DELETE /api/items/:id (delete)
+  </items>
+</api_endpoints_summary>
+```
+
+### ui_layout
+```xml
+<ui_layout>
+  <main_structure>
+    - Header with navigation and user menu
+    - Sidebar for navigation (collapsible on mobile)
+    - Main content area
+    - Footer (optional)
+  </main_structure>
+  <sidebar>
+    - Logo at top
+    - Navigation links
+    - User profile at bottom
+  </sidebar>
+</ui_layout>
+```
+
+### design_system
+```xml
+<design_system>
+  <color_palette>
+    - Primary: #3B82F6 (blue)
+    - Background: #FFFFFF (light), #1A1A1A (dark)
+    - Text: #1F2937 (light), #E5E5E5 (dark)
+    - Error: #EF4444
+    - Success: #10B981
+  </color_palette>
+  <typography>
+    - Font family: Inter, system-ui, sans-serif
+    - Headings: font-semibold
+    - Body: font-normal
+  </typography>
+</design_system>
+```
+
+### key_interactions
+```xml
+<key_interactions>
+  <user_flow_login>
+    1. User navigates to /login
+    2. User enters email and password
+    3. System validates credentials
+    4. On success: redirect to dashboard
+    5. On failure: show error message
+  </user_flow_login>
+  <user_flow_create_item>
+    1. User clicks "Create New" button
+    2. Modal form opens
+    3. User fills required fields
+    4. User clicks save
+    5. Item appears in list with success toast
+  </user_flow_create_item>
+</key_interactions>
+```
+
+### implementation_steps
+```xml
+<implementation_steps>
+  <step number="1">
+    <title>Project Setup</title>
+    <tasks>
+      - Initialize frontend with Vite
+      - Set up Express backend
+      - Create database schema
+      - Configure environment variables
+    </tasks>
+  </step>
+  <step number="2">
+    <title>Authentication</title>
+    <tasks>
+      - Implement registration
+      - Implement login/logout
+      - Add session management
+      - Create protected routes
+    </tasks>
+  </step>
+</implementation_steps>
+```
+
+### success_criteria
+```xml
+<success_criteria>
+  <functionality>
+    - All features work as specified
+    - No console errors in browser
+    - Data persists correctly in database
+  </functionality>
+  <user_experience>
+    - Responsive on all device sizes
+    - Fast load times (< 2s)
+    - Clear feedback for all actions
+  </user_experience>
+  <technical_quality>
+    - Clean code structure
+    - Proper error handling
+    - Secure authentication
+  </technical_quality>
+</success_criteria>
+```
+
+## Feature Count Guidelines
+
+The Initializer agent expects features distributed across categories:
+
+| Project Complexity | Total Features | Categories |
+|--------------------|----------------|------------|
+| Simple CLI/utility | 100-150 | 5-8 |
+| Medium web app | 200-250 | 10-15 |
+| Complex full-stack | 300-400 | 15-20 |
+
+## GSD to Autocoder Mapping
+
+When converting from GSD codebase mapping:
+
+| GSD Document | Maps To |
+|--------------|---------|
+| STACK.md Languages | `<technology_stack>` |
+| STACK.md Runtime | `<prerequisites>` |
+| STACK.md Frameworks | `<frontend>`, `<backend>` |
+| ARCHITECTURE.md Pattern | `<overview>` |
+| ARCHITECTURE.md Layers | `<core_features>` categories |
+| ARCHITECTURE.md Data Flow | `<key_interactions>` |
+| ARCHITECTURE.md Entry Points | `<implementation_steps>` |
+| STRUCTURE.md Layout | Informs feature organization |
+| INTEGRATIONS.md APIs | `<api_endpoints_summary>` |
+| INTEGRATIONS.md Services | `<prerequisites>` |