mirror of
https://github.com/leonvanzyl/autocoder.git
synced 2026-01-30 06:12:06 +00:00
Merge pull request #57 from simfor99/feature/gsd-integration
feat: add GSD integration skill for existing projects
This commit is contained in:
Leon van Zyl
10
.claude/commands/gsd-to-autocoder-spec.md
Normal file
10
.claude/commands/gsd-to-autocoder-spec.md
Normal file
@@ -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
|
||||
221
.claude/skills/gsd-to-autocoder-spec/SKILL.md
Normal file
221
.claude/skills/gsd-to-autocoder-spec/SKILL.md
Normal file
@@ -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 |
|
||||
@@ -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>` |
|
||||
Reference in New Issue
Block a user