diff --git a/.codex/config/project.md b/.codex/config/project.md new file mode 100644 index 0000000..da5b59c --- /dev/null +++ b/.codex/config/project.md @@ -0,0 +1,32 @@ +# Codex Configuration + +## Project Settings + +This project is optimized for Codex CLI autonomous coding. + +## Key Files + +- CODEX.md - Root instructions (this file guides Codex) +- .codex/prompts/ - Pre-built prompts for each development phase +- features/INDEX.md - Feature tracking and status +- docs/PRD.md - Product Requirements Document + +## Development Workflow + +1. Requirements → 2. Architecture → 3. Frontend → 4. Backend → 5. QA → 6. Deploy + +Each phase uses `codex exec` with natural language prompts. +See CODEX.md for example commands. + +## Conventions + +- Feature IDs: PROJ-1, PROJ-2, etc. +- Commits: feat(PROJ-X): description +- Tests: co-located with source files +- shadcn/ui first: never recreate installed components + +## Recommended Flags + +- `--full-auto` for feature development (auto-approves changes) +- `--yolo` for quick refactoring (no sandbox) +- Interactive (default) for review/debugging diff --git a/.codex/prompts/architecture.md b/.codex/prompts/architecture.md new file mode 100644 index 0000000..21f966f --- /dev/null +++ b/.codex/prompts/architecture.md @@ -0,0 +1,21 @@ +# Architecture Prompt Template + +Use this prompt structure for technical design: + +``` +Read the feature spec at features/PROJ-X-feature-name.md. +Design the technical architecture and add a Tech Design section to the spec file. + +Focus on: +- Component structure (for frontend) +- API design (endpoints, request/response shapes) +- Database schema (tables, relationships, indexes) +- Implementation order (what to build first, dependencies) +- Security considerations +- Tech stack decisions (libraries, patterns) +``` + +Example: +``` + exec "Read features/PROJ-1-login.md. Design the auth architecture: JWT vs sessions, database schema for users, password hashing approach, and implementation order." +``` \ No newline at end of file diff --git a/.codex/prompts/backend.md b/.codex/prompts/backend.md new file mode 100644 index 0000000..797f6f7 --- /dev/null +++ b/.codex/prompts/backend.md @@ -0,0 +1,23 @@ +# Backend Implementation Prompt Template + +Use this prompt structure for backend development: + +``` +Read features/INDEX.md and the feature spec at features/PROJ-X-feature-name.md. +Implement the backend components. + +Focus on: +- API endpoints (create, read, update, delete) +- Database queries (SQL, migrations) +- Business logic (validation, error handling) +- Authentication/Authorization if needed +- Rate limiting and security headers + +Write tests in the appropriate tests/ directory. +Follow the coding rules in .opencode/rules/ or .codex/config/project.md. +``` + +Example: +``` + exec "Read features/PROJ-1-login.md. Implement the login API: POST /auth/login endpoint, password verification, JWT generation. Add migration for users table. Write PHPUnit tests." +``` \ No newline at end of file diff --git a/.codex/prompts/deploy.md b/.codex/prompts/deploy.md new file mode 100644 index 0000000..552b671 --- /dev/null +++ b/.codex/prompts/deploy.md @@ -0,0 +1,27 @@ +# Deploy Prompt Template + +Use this prompt structure for deployment: + +``` +Read the feature spec at features/PROJ-X-feature-name.md. +Deploy the implemented feature to production. + +Steps: +1. Run build/lint/tests locally +2. Create git tag: v1.0.0-PROJ-X +3. Push to origin +4. Trigger deployment pipeline +5. Verify production URL works +6. Update feature spec with deployment status: + +## Deployment +**Status:** ✅ Deployed +**Deployed:** YYYY-MM-DD +**Production URL:** https://... +**Git Tag:** v1.0.0-PROJ-X +``` + +Example: +``` + exec "Deploy PROJ-1-login: run npm build, create tag v1.0.0-PROJ-1, push. Verify at https://www.example.com. Update feature spec." +``` \ No newline at end of file diff --git a/.codex/prompts/frontend.md b/.codex/prompts/frontend.md new file mode 100644 index 0000000..f887787 --- /dev/null +++ b/.codex/prompts/frontend.md @@ -0,0 +1,24 @@ +# Frontend Implementation Prompt Template + +Use this prompt structure for frontend development: + +``` +Read features/INDEX.md and the feature spec at features/PROJ-X-feature-name.md. +Implement the UI components. + +Focus on: +- Component structure (React/Vue components) +- State management +- Form handling and validation +- Responsive design +- Accessibility (a11y) +- Integration with backend API + +Write tests co-located next to source files (e.g., LoginForm.test.tsx next to LoginForm.tsx). +Follow the coding rules in .opencode/rules/frontend.md or .codex/config/project.md. +``` + +Example: +``` + exec "Read features/PROJ-1-login.md. Build the login form component: email/password inputs, validation, submit handler, error display. Use shadcn/ui components. Write tests." +``` \ No newline at end of file diff --git a/.codex/prompts/qa.md b/.codex/prompts/qa.md new file mode 100644 index 0000000..496de2c --- /dev/null +++ b/.codex/prompts/qa.md @@ -0,0 +1,28 @@ +# QA Prompt Template + +Use this prompt structure for quality assurance: + +``` +Read the feature spec at features/PROJ-X-feature-name.md. +Test the implementation against each acceptance criterion. + +Verify: +- [ ] Each acceptance criterion passes +- [ ] Edge cases handled gracefully +- [ ] Error messages are user-friendly +- [ ] No security vulnerabilities +- [ ] Performance is acceptable + +Document results in the feature spec: +- [x] AC-1: criterion passed +- [ ] AC-2: criterion failed (describe bug) + +Run: + +Fix any failures before marking as complete. +``` + +Example: +``` + exec "Test the login feature: verify email/password validation, test with wrong credentials, check rate limiting. Run npm test. Document results in features/PROJ-1-login.md." +``` \ No newline at end of file diff --git a/.codex/prompts/requirements.md b/.codex/prompts/requirements.md new file mode 100644 index 0000000..18c5ee3 --- /dev/null +++ b/.codex/prompts/requirements.md @@ -0,0 +1,25 @@ +# Requirements Prompt Template + +Use this prompt structure for creating feature specifications: + +``` +Read docs//doku/PRD.md to understand the project vision and constraints. +Read features/INDEX.md to see existing features and the next available PROJ-X ID. + +[Describe the feature idea clearly] + +Create a feature specification in features/PROJ-X-feature-name.md with: +- Feature name and ID +- User stories (3-5, with: As a [role], I want [action], so that [benefit]) +- Acceptance criteria (testable, specific) +- Edge cases (error handling, edge inputs, boundary conditions) +- Dependencies (other features required) +- Implementation notes (optional) + +Update features/INDEX.md with the new feature status. +``` + +Example: +``` + exec "Read docs/www.example.com/doku/PRD.md and features/INDEX.md. Create a feature spec for user authentication with email/password login, including: user stories for login/logout, acceptance criteria for valid/invalid credentials, edge cases for locked accounts and rate limiting." +``` \ No newline at end of file diff --git a/.opencode/config/project.md b/.opencode/config/project.md new file mode 100644 index 0000000..e6dfd78 --- /dev/null +++ b/.opencode/config/project.md @@ -0,0 +1,40 @@ +# OpenCode Project Configuration + +## Project Info + +- **Name:** AI Coding Starter Kit - Opencode - PHP Edition +- **Repository:** https://git.shadow-land.de/madgerm/ai-coding-starter-kit-opencode +- **Description:** PHP project template with AI-powered development workflow optimized for OpenCode. SQLite-first dev, MariaDB/PostgreSQL production. + +## Skills + +The following skills are available in `.opencode/skills/`: + +| Skill | Description | +|-------|-------------| +| `requirements` | Creates feature specs with user stories, AC, edge cases | +| `architecture` | Designs tech architecture (class structure, DB schema) | +| `php` | Builds PHP code, migrations, and tests | +| `qa` | Tests features against acceptance criteria | +| `docs` | Documents API endpoints and maintains wiki structure | +| `deploy` | Deploys to traditional hosting (LAMP, Docker, bare metal) | + +## Agents + +Heavy tasks (implementation, QA) run as forked agents with isolated contexts. + +## Rules + +Auto-applied coding standards in `.opencode/rules/`: +- `general.md` - Git workflow, feature tracking +- `php.md` - PHP code standards, portable SQL +- `database.md` - SQLite/MariaDB/PostgreSQL portability +- `security.md` - Secrets, headers, auth + +## Default Branch + +`main` + +## Feature ID Pattern + +`PROJ-1`, `PROJ-2`, etc. (sequential) \ No newline at end of file diff --git a/.opencode/prompts/architecture.md b/.opencode/prompts/architecture.md new file mode 100644 index 0000000..21f966f --- /dev/null +++ b/.opencode/prompts/architecture.md @@ -0,0 +1,21 @@ +# Architecture Prompt Template + +Use this prompt structure for technical design: + +``` +Read the feature spec at features/PROJ-X-feature-name.md. +Design the technical architecture and add a Tech Design section to the spec file. + +Focus on: +- Component structure (for frontend) +- API design (endpoints, request/response shapes) +- Database schema (tables, relationships, indexes) +- Implementation order (what to build first, dependencies) +- Security considerations +- Tech stack decisions (libraries, patterns) +``` + +Example: +``` + exec "Read features/PROJ-1-login.md. Design the auth architecture: JWT vs sessions, database schema for users, password hashing approach, and implementation order." +``` \ No newline at end of file diff --git a/.opencode/prompts/backend.md b/.opencode/prompts/backend.md new file mode 100644 index 0000000..797f6f7 --- /dev/null +++ b/.opencode/prompts/backend.md @@ -0,0 +1,23 @@ +# Backend Implementation Prompt Template + +Use this prompt structure for backend development: + +``` +Read features/INDEX.md and the feature spec at features/PROJ-X-feature-name.md. +Implement the backend components. + +Focus on: +- API endpoints (create, read, update, delete) +- Database queries (SQL, migrations) +- Business logic (validation, error handling) +- Authentication/Authorization if needed +- Rate limiting and security headers + +Write tests in the appropriate tests/ directory. +Follow the coding rules in .opencode/rules/ or .codex/config/project.md. +``` + +Example: +``` + exec "Read features/PROJ-1-login.md. Implement the login API: POST /auth/login endpoint, password verification, JWT generation. Add migration for users table. Write PHPUnit tests." +``` \ No newline at end of file diff --git a/.opencode/prompts/deploy.md b/.opencode/prompts/deploy.md new file mode 100644 index 0000000..552b671 --- /dev/null +++ b/.opencode/prompts/deploy.md @@ -0,0 +1,27 @@ +# Deploy Prompt Template + +Use this prompt structure for deployment: + +``` +Read the feature spec at features/PROJ-X-feature-name.md. +Deploy the implemented feature to production. + +Steps: +1. Run build/lint/tests locally +2. Create git tag: v1.0.0-PROJ-X +3. Push to origin +4. Trigger deployment pipeline +5. Verify production URL works +6. Update feature spec with deployment status: + +## Deployment +**Status:** ✅ Deployed +**Deployed:** YYYY-MM-DD +**Production URL:** https://... +**Git Tag:** v1.0.0-PROJ-X +``` + +Example: +``` + exec "Deploy PROJ-1-login: run npm build, create tag v1.0.0-PROJ-1, push. Verify at https://www.example.com. Update feature spec." +``` \ No newline at end of file diff --git a/.opencode/prompts/frontend.md b/.opencode/prompts/frontend.md new file mode 100644 index 0000000..f887787 --- /dev/null +++ b/.opencode/prompts/frontend.md @@ -0,0 +1,24 @@ +# Frontend Implementation Prompt Template + +Use this prompt structure for frontend development: + +``` +Read features/INDEX.md and the feature spec at features/PROJ-X-feature-name.md. +Implement the UI components. + +Focus on: +- Component structure (React/Vue components) +- State management +- Form handling and validation +- Responsive design +- Accessibility (a11y) +- Integration with backend API + +Write tests co-located next to source files (e.g., LoginForm.test.tsx next to LoginForm.tsx). +Follow the coding rules in .opencode/rules/frontend.md or .codex/config/project.md. +``` + +Example: +``` + exec "Read features/PROJ-1-login.md. Build the login form component: email/password inputs, validation, submit handler, error display. Use shadcn/ui components. Write tests." +``` \ No newline at end of file diff --git a/.opencode/prompts/qa.md b/.opencode/prompts/qa.md new file mode 100644 index 0000000..496de2c --- /dev/null +++ b/.opencode/prompts/qa.md @@ -0,0 +1,28 @@ +# QA Prompt Template + +Use this prompt structure for quality assurance: + +``` +Read the feature spec at features/PROJ-X-feature-name.md. +Test the implementation against each acceptance criterion. + +Verify: +- [ ] Each acceptance criterion passes +- [ ] Edge cases handled gracefully +- [ ] Error messages are user-friendly +- [ ] No security vulnerabilities +- [ ] Performance is acceptable + +Document results in the feature spec: +- [x] AC-1: criterion passed +- [ ] AC-2: criterion failed (describe bug) + +Run: + +Fix any failures before marking as complete. +``` + +Example: +``` + exec "Test the login feature: verify email/password validation, test with wrong credentials, check rate limiting. Run npm test. Document results in features/PROJ-1-login.md." +``` \ No newline at end of file diff --git a/.opencode/prompts/requirements.md b/.opencode/prompts/requirements.md new file mode 100644 index 0000000..18c5ee3 --- /dev/null +++ b/.opencode/prompts/requirements.md @@ -0,0 +1,25 @@ +# Requirements Prompt Template + +Use this prompt structure for creating feature specifications: + +``` +Read docs//doku/PRD.md to understand the project vision and constraints. +Read features/INDEX.md to see existing features and the next available PROJ-X ID. + +[Describe the feature idea clearly] + +Create a feature specification in features/PROJ-X-feature-name.md with: +- Feature name and ID +- User stories (3-5, with: As a [role], I want [action], so that [benefit]) +- Acceptance criteria (testable, specific) +- Edge cases (error handling, edge inputs, boundary conditions) +- Dependencies (other features required) +- Implementation notes (optional) + +Update features/INDEX.md with the new feature status. +``` + +Example: +``` + exec "Read docs/www.example.com/doku/PRD.md and features/INDEX.md. Create a feature spec for user authentication with email/password login, including: user stories for login/logout, acceptance criteria for valid/invalid credentials, edge cases for locked accounts and rate limiting." +``` \ No newline at end of file diff --git a/.opencode/rules/backend.md b/.opencode/rules/backend.md index 6ba54fe..ea31883 100644 --- a/.opencode/rules/backend.md +++ b/.opencode/rules/backend.md @@ -1,20 +1,74 @@ # Backend Rules -## PHP +Backend development rules for PHP, databases, and APIs. -- PHP 8+ Syntax -- Prepared Statements für DB Queries -- Input Validation immer auf Server-Seite -- Keine secrets in Code — .env nutzen +## PHP Code -## REST API +- Follow PSR-12 coding standard +- Use strict types: `declare(strict_types=1);` +- Use typed properties and return types +- Maximum function length: ~40 lines +- No code duplication — extract to helper functions -- JSON als Standard-Format -- HTTP Status Codes korrekt nutzen -- GET/POST/etc. semantisch richtig +## API Design -## SQLite +### RESTful Conventions -- Transactions für mehrere Writes -- FOREIGN KEY Constraints aktiviert -- Indexes auf häufige Query-Spalten +| Method | Path | Action | +|--------|------|--------| +| GET | /users | List users | +| GET | /users/{id} | Get single user | +| POST | /users | Create user | +| PUT | /users/{id} | Update user | +| DELETE | /users/{id} | Delete user | + +### Response Format + +```php +// Success +json_response(['data' => $user, 'status' => 200]); + +// Error +json_response(['error' => 'Not found', 'status' => 404]); + +// List with pagination +json_response([ + 'data' => $users, + 'total' => $total, + 'page' => $page, + 'per_page' => $perPage +]); +``` + +### Status Codes + +- `200` OK +- `201` Created +- `204` No Content (successful DELETE) +- `400` Bad Request +- `401` Unauthorized +- `403` Forbidden +- `404` Not Found +- `422` Unprocessable Entity (validation error) +- `500` Internal Server Error + +## Validation + +- Validate in the controller/action before business logic +- Return `422` with field-specific errors on validation failure +- Never trust user input — validate everything + +## Database + +- Use PDO with parameterized queries (no string interpolation) +- Use transactions for multi-step operations +- Use indexes on columns used in WHERE/JOIN +- Avoid N+1 queries +- See `database.md` for SQLite/MariaDB/PostgreSQL portability + +## Testing + +- Unit test business logic in isolation +- Integration test API endpoints +- Test happy path AND error paths +- Mock database in unit tests where practical diff --git a/.opencode/rules/database.md b/.opencode/rules/database.md new file mode 100644 index 0000000..b56dec6 --- /dev/null +++ b/.opencode/rules/database.md @@ -0,0 +1,80 @@ +# Database Rules + +SQLite for development, MariaDB/PostgreSQL for production. Write portable SQL. + +## Development Database + +- Use SQLite for local development (zero-config, no server) +- Database file: `database.sqlite` in project root +- Create with: `touch database.sqlite` + +## SQL Portability + +### Use Standard SQL Only + +- `CURRENT_TIMESTAMP` — works on SQLite, MariaDB, PostgreSQL +- `INTEGER PRIMARY KEY` — portable (mapped to SERIAL/BIGSERIAL) +- `TEXT` — portable (avoid VARCHAR length constraints) +- `DATETIME` — portable across all three databases + +### Avoid + +| Pattern | Why | Alternative | +|---------|-----|-------------| +| `REPLACE INTO` | Deletes then inserts (data loss) | `UPDATE ...; INSERT IF 0 rows affected` | +| `NOW()` | SQLite/MariaDB specific | `CURRENT_TIMESTAMP` | +| `GROUP_CONCAT()` | Not in SQLite | Application-level aggregation | +| `IFNULL()` | SQLite syntax | `COALESCE()` (standard) | +| Database-specific functions | Locks you in | Do it in application code | + +### Boolean Fields + +SQLite has no BOOLEAN — use INTEGER (0/1): + +```sql +CREATE TABLE settings ( + dark_mode INTEGER DEFAULT 0, + notifications INTEGER DEFAULT 1 +); +``` + +### String Concatenation + +Do string concatenation in PHP, not SQL. + +### Upsert Pattern + +```php +// Safe upsert (works on all databases) +$affected = $pdo->prepare( + 'UPDATE users SET name = ? WHERE id = ?' +)->execute([$name, $id]); + +if ($affected === 0) { + $pdo->prepare( + 'INSERT INTO users (id, name) VALUES (?, ?)' + )->execute([$id, $name]); +} +``` + +## Migrations + +- Store migrations in `migrations/` directory +- Name format: `001_description.sql`, `002_description.sql` +- Each migration must be idempotent (use `IF NOT EXISTS`) +- Run migrations on every environment + +## Indexes + +- Index columns used in `WHERE`, `JOIN`, `ORDER BY` +- Composite indexes: put most selective column first +- Don't over-index (write performance cost) + +## No N+1 Queries + +- Use JOINs or batch queries +- Eager load relationships when needed + +## Transactions + +Use transactions for any operation that modifies more than one table or row. diff --git a/.opencode/rules/frontend.md b/.opencode/rules/frontend.md index 4c4823d..89bce3c 100644 --- a/.opencode/rules/frontend.md +++ b/.opencode/rules/frontend.md @@ -1,17 +1,32 @@ # Frontend Rules -## HTML +Frontend development rules for React, Next.js, Tailwind CSS, and shadcn/ui. -- Semantisches HTML5 -- Accessibility beachten (a11y) +## shadcn/ui Components -## CSS +- ALWAYS check `src/components/ui/` first before creating new components +- NEVER recreate a component that already exists in shadcn/ui +- If missing component: `npx shadcn@latest add ` -- CSS Variables für Theming -- Mobile-First Ansatz -- Keine inline Styles (außer dynamisch) +## Styling -## JS +- Use Tailwind CSS utility classes (never raw CSS) +- Follow existing patterns in the codebase +- Use `clsx` and `tailwind-merge` for conditional classes -- Vanilla JS bevorzugt, kein Framework-Overhead -- ES6+ Syntax +## Component Standards + +- All components must be TypeScript (`.tsx`) +- Use proper TypeScript types for props +- Follow existing component patterns + +## Testing + +- Unit tests co-located next to source files +- Pattern: `ComponentName.test.tsx` next to `ComponentName.tsx` +- Use `@testing-library/react` for React tests + +## Lint + +- Run `npm run lint` after every change +- Fix lint errors before committing \ No newline at end of file diff --git a/.opencode/rules/general.md b/.opencode/rules/general.md index 151e0bf..6c3c4f5 100644 --- a/.opencode/rules/general.md +++ b/.opencode/rules/general.md @@ -1,20 +1,35 @@ # General Rules -## Projekt Start +General development rules for the AI Coding Starter Kit. -Bei einem neuen Projekt: -1. README.md lesen / erstellen -2. AGENTS.md lesen -3. docs/planung/ öffnen und Projektstruktur verstehen +## Feature Tracking -## Naming +- All features MUST be tracked in `features/INDEX.md` +- Feature IDs are sequential: PROJ-1, PROJ-2, etc. +- Never skip IDs or use non-sequential numbering -- Kleinbuchstaben mit Bindestrichen: `mein-projekt` -- Subdomains als Verzeichnisse unter `www/` -- Document-Root immer `public/` +## Git Workflow -## Git Flow +- Commits: `feat(PROJ-X): description`, `fix(PROJ-X): description` +- Never commit secrets, API keys, or credentials +- Always read file before modifying (never assume contents) -1. Branch für Feature: `feature/` -2. Commit oft mit aussagekräftigen Messages -3. Merge via PR oder direkt (bei kleinen Fixes) +## File Structure + +- Feature specs: `features/PROJ-X-feature-name.md` +- Tests: co-located next to source (`*.test.ts` next to `*.ts`) +- shadcn/ui components: `src/components/ui/` (NEVER recreate) + +## State Management + +- State lives in files, not in memory +- Re-read files when context is compacted +- All progress in markdown files (INDEX.md, feature specs) + +## Context Recovery + +If context is compacted: +1. Re-read relevant feature spec +2. Check `git diff` for uncommitted changes +3. Continue from where you left off +4. Never restart from scratch without checking progress \ No newline at end of file diff --git a/.opencode/rules/php.md b/.opencode/rules/php.md new file mode 100644 index 0000000..b7a5f2b --- /dev/null +++ b/.opencode/rules/php.md @@ -0,0 +1,67 @@ +# PHP Rules + +PHP development rules for portable, maintainable code. + +## Code Style + +- Follow PSR-12 coding standard +- Use PHP-CS-Fixer or Laravel Pint for formatting +- All new files must have ` true, 'secure' => true])` + +## Security Headers + +For production, set these headers: + +``` +X-Content-Type-Options: nosniff +X-Frame-Options: DENY +X-XSS-Protection: 1; mode=block +Referrer-Policy: strict-origin-when-cross-origin +Content-Security-Policy: default-src 'self' +``` + +## File Uploads + +- Never trust the filename — generate a new one +- Store files outside web root +- Validate MIME type server-side (not just by extension) +- Set file size limits + +## Dependencies + +- Keep Composer dependencies up to date: `composer outdated` +- Run `composer audit` regularly +- Update known vulnerable packages immediately \ No newline at end of file diff --git a/.opencode/skills/architecture/SKILL.md b/.opencode/skills/architecture/SKILL.md new file mode 100644 index 0000000..88746f3 --- /dev/null +++ b/.opencode/skills/architecture/SKILL.md @@ -0,0 +1,70 @@ +--- +name: architecture +description: Designs technical architecture for feature specs +category: development +--- + +# Solution Architect + +Designs the technical architecture for a feature and adds it to the feature spec. + +## When to Use + +Run this skill after `/requirements` to design the technical approach: + +``` +/architecture features/PROJ-X-feature-name.md +``` + +## Skill Steps + +1. **Read feature spec** + - Read the feature spec file created by `/requirements` + +2. **Design architecture** + - **Component hierarchy**: List all components needed + - **API design**: Endpoints (method, path, request/response shapes) + - **Database schema**: Tables, columns, RLS policies (if Supabase) + - **Implementation order**: What to build first, dependencies + +3. **Add Tech Design section** + - Append "Tech Design" section to the feature spec + +4. **Update tracking** + - Update `features/INDEX.md` status to "Designed" + +5. **Suggest next step** + - Recommend running `/frontend` or `/backend` next + +## Tech Design Section Format + +```markdown +## Tech Design + +### Components +- ComponentName: description, props + +### API Endpoints +| Method | Path | Request | Response | +|--------|------|---------|----------| +| POST | /api/entities | {...} | {id, ...} | + +### Database Schema +- Table: entities + - id: uuid (PK) + - name: text + - created_at: timestamp + +### Implementation Order +1. Create database schema +2. Build API endpoints +3. Build UI components +4. Add tests +``` + +## Context Recovery + +If context is compacted: +1. Re-read the feature spec +2. Check if Tech Design section already exists +3. Continue from implementation order \ No newline at end of file diff --git a/.opencode/skills/backend/SKILL.md b/.opencode/skills/backend/SKILL.md new file mode 100644 index 0000000..99598bc --- /dev/null +++ b/.opencode/skills/backend/SKILL.md @@ -0,0 +1,64 @@ +--- +name: backend +description: Builds APIs, database schemas, and RLS policies with Supabase +category: development +--- + +# Backend Developer + +Builds API endpoints, database schemas, and RLS policies for a feature. + +## When to Use + +``` +/backend features/PROJ-X-feature-name.md +``` + +## Skill Steps + +1. **Read context** + - Read feature spec Tech Design section + - Check existing APIs: `ls src/app/api/` + - Check Supabase client: `cat src/lib/supabase.ts` + +2. **Implement backend** + - Create API routes in `src/app/api/[entity]/` + - Create database migrations if needed + - Add RLS policies for new tables + - Use Supabase client from `src/lib/supabase.ts` + +3. **Write tests** + - Unit tests for all endpoints + - Integration tests for API routes + +4. **Verify** + - Run `npm test` to ensure tests pass + +5. **Update tracking** + - Mark feature as "Backend Done" in `features/INDEX.md` + +6. **Suggest next step** + - Recommend `/qa` next + +## API Route Pattern + +``` +src/app/api/[entity]/ +├── route.ts # GET, POST +├── [id]/route.ts # GET, PUT, DELETE +``` + +## Rules + +- Use Supabase client from `src/lib/supabase.ts` +- Follow existing route patterns +- Add RLS policies for all new tables +- Write tests for all endpoints +- Run `npm test` after implementation + +## Context Recovery + +If context is compacted: +1. Re-read feature spec Tech Design +2. Check `git diff` for uncommitted changes +3. Continue from next endpoint \ No newline at end of file diff --git a/.opencode/skills/deploy/SKILL.md b/.opencode/skills/deploy/SKILL.md new file mode 100644 index 0000000..5735a47 --- /dev/null +++ b/.opencode/skills/deploy/SKILL.md @@ -0,0 +1,60 @@ +--- +name: deploy +description: Deploys to Vercel with production-ready checks +category: devops +--- + +# DevOps + +Deploys the project to Vercel with production-ready checks. + +## When to Use + +``` +/deploy +``` + +## Skill Steps + +1. **Pre-deployment checks** + - Run `npm run build` - must succeed + - Run `npm run lint` - no errors + +2. **Deploy** + - Run `vercel --prod` + - Capture deployment URL + +3. **Verify deployment** + - Test the deployed URL + - Run smoke tests on key features + +4. **Post-deployment** + - Update `features/INDEX.md` with deployment URL + - Mark feature as "Deployed" + +## Rules + +- Build must succeed before deployment +- Lint must pass before deployment +- Verify deployment URL is accessible + +## If Build Fails + +1. Fix compilation errors +2. Re-run `npm run build` +3. Re-run `npm run lint` +4. Then deploy + +## If Lint Fails + +1. Run `npm run lint:fix` +2. Commit fixes +3. Re-run `npm run lint` +4. Then deploy + +## Context Recovery + +If context is compacted during deployment: +1. Check if `vercel` deployment completed +2. Verify deployment URL +3. Mark as deployed if successful \ No newline at end of file diff --git a/.opencode/skills/docs/SKILL.md b/.opencode/skills/docs/SKILL.md new file mode 100644 index 0000000..6bedca1 --- /dev/null +++ b/.opencode/skills/docs/SKILL.md @@ -0,0 +1,109 @@ +--- +name: docs +description: Documents API endpoints, generates wiki structure, and tracks documentation coverage +category: development +--- + +# Documentation Engineer + +Documents API endpoints, maintains wiki structure, and reports documentation gaps. + +## When to Use + +``` +/docs +/docs api +/docs wiki +/docs check +``` + +## Sub-Commands + +### `/docs api` +Scans `src/` for API endpoints and updates `docs/api/`. + +### `/docs wiki` +Suggests or updates wiki structure in `docs/wiki/`. + +### `/docs check` +Reports which endpoints/classes lack documentation. + +## Skill Steps + +### 1. Scan for API Endpoints +- Search `src/` for route files (REST patterns: `*Route.php`, `*Controller.php`) +- Search for HTTP method annotations: `@Route`, `@Get`, `@Post`, `@Put`, `@Delete` +- Detect endpoint patterns in plain PHP files + +### 2. Update API Documentation +- Create/update `docs/api/ENDPOINTS.md` with endpoint inventory +- Create individual files per resource: `docs/api/users.md`, `docs/api/tasks.md` +- Format: + +```markdown +# Users API + +## Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| GET | /api/users | List all users | +| GET | /api/users/{id} | Get single user | +| POST | /api/users | Create user | +| PUT | /api/users/{id} | Update user | +| DELETE | /api/users/{id} | Delete user | + +## Request/Response Examples + +### GET /api/users +**Response:** +```json +{ + "data": [...], + "total": 42, + "page": 1, + "per_page": 20 +} +``` +``` + +### 3. Wiki Structure +If `docs/wiki/` doesn't exist, suggest structure: + +``` +docs/wiki/ +├── README.md <- Wiki home +├── getting-started.md <- Setup guide +├── api-reference.md <- API overview +├── database.md <- DB schema +└── deployment.md <- Hosting guide +``` + +### 4. Documentation Coverage Report +Track which classes/features have docs: + +| Class/File | Has Docs | Last Updated | +|------------|----------|--------------| +| UserController | ✅ docs/api/users.md | 2026-01-15 | +| TaskController | ❌ missing | - | + +## Output + +- `docs/api/*.md` - API endpoint documentation +- `docs/wiki/README.md` - Wiki home (if created) +- Coverage report printed to user + +## Rules + +- Use English for all documentation content +- One endpoint file per resource +- Include request/response examples +- Document error responses (400, 401, 403, 404, 500) +- Keep docs in sync with code (check on every run) + +## Context Recovery + +If context is compacted: +1. Re-scan `src/` for endpoint files +2. Check which docs already exist +3. Continue from missing documentation diff --git a/.opencode/skills/frontend/SKILL.md b/.opencode/skills/frontend/SKILL.md new file mode 100644 index 0000000..9d02bdf --- /dev/null +++ b/.opencode/skills/frontend/SKILL.md @@ -0,0 +1,59 @@ +--- +name: frontend +description: Builds UI components with React, Tailwind CSS, and shadcn/ui +category: development +--- + +# Frontend Developer + +Builds the UI components for a feature using React, Next.js, Tailwind CSS, and shadcn/ui. + +## When to Use + +``` +/frontend features/PROJ-X-feature-name.md +``` + +## Skill Steps + +1. **Read context** + - Read `features/INDEX.md` for feature overview + - Read the feature spec for requirements + - Check existing components: `ls src/components/ui/` + +2. **Check shadcn/ui availability** + - List installed components in `src/components/ui/` + - Install missing with: `npx shadcn@latest add ` + +3. **Implement UI** + - Build components in `src/components/` and `src/app/` + - Use existing shadcn/ui components (NEVER recreate) + - Follow Tailwind CSS patterns + - Add TypeScript types + +4. **Write tests** + - Unit tests next to source files (`*.test.ts` next to `*.ts`) + +5. **Lint** + - Run `npm run lint` after changes + +6. **Update tracking** + - Mark feature as "Frontend Done" in `features/INDEX.md` + +7. **Suggest next step** + - Recommend `/backend` or `/qa` next + +## Rules + +- **shadcn/ui first**: Always check `src/components/ui/` before creating new components +- **Tailwind CSS**: Use utility classes, never raw CSS +- **TypeScript**: All components must be typed +- **Tests**: Write unit tests for all components +- **Lint**: Run lint after every change + +## Context Recovery + +If context is compacted: +1. Re-read feature spec +2. Check `git diff` for uncommitted changes +3. Continue implementation \ No newline at end of file diff --git a/.opencode/skills/help/SKILL.md b/.opencode/skills/help/SKILL.md index 5ed8d7d..27a541c 100644 --- a/.opencode/skills/help/SKILL.md +++ b/.opencode/skills/help/SKILL.md @@ -16,15 +16,22 @@ skeleton/ ├── .gitignore ✓ ├── AGENTS.md ✓ ├── .opencode/ -│ ├── settings.json ✓ +│ ├── config/project.md ✓ │ ├── rules/ ✓ │ └── skills/ ✓ +├── .codex/ +│ ├── config/project.md ✓ +│ └── prompts/ ✓ +├── .shared/prompts/ ✓ ├── docs/ -│ ├── doku/ ✓ -│ └── planung/ ✓ -├── www/ -│ ├── api/public/ ✓ -│ ├── game/public/ ✓ -│ └── www/public/ ✓ -└── README.md ✓ -``` +│ └── / +│ ├── doku/ ✓ +│ ├── planung/ ✓ +│ └── todos/ ✓ +├── features/ +│ ├── INDEX.md ✓ +│ └── README.md ✓ +└── www/ + └── / + └── public/ ✓ +``` \ No newline at end of file diff --git a/.opencode/skills/php/SKILL.md b/.opencode/skills/php/SKILL.md new file mode 100644 index 0000000..3a0cad1 --- /dev/null +++ b/.opencode/skills/php/SKILL.md @@ -0,0 +1,90 @@ +--- +name: php +description: Builds PHP code, database migrations, and PHPUnit tests +category: development +--- + +# PHP Developer + +Builds PHP code, database migrations, and tests for a feature. + +## When to Use + +``` +/php features/PROJ-X-feature-name.md +``` + +## Skill Steps + +1. **Read context** + - Read `features/INDEX.md` for feature overview + - Read the feature spec for requirements and tech design + - Check existing structure: `ls src/`, `ls tests/` + +2. **Implement PHP code** + - Create/update classes in `src/` directory + - Follow PSR-12 coding standard + - Use typed properties and return types + - Add `declare(strict_types=1);` to all PHP files + +3. **Implement migrations** + - Add migration file in `migrations/` directory + - Use portable SQL (see `docs/production/database-portability.md`) + - Use `IF NOT EXISTS` for idempotency + +4. **Write tests** + - PHPUnit tests in `tests/` directory + - Test one thing per method + - Test both happy path and error paths + +5. **Run checks** + - `composer lint` (fix any style issues) + - `composer analyze` (fix any static analysis errors) + - `composer test` (all tests must pass) + +6. **Update tracking** + - Mark feature as "Implemented" in `features/INDEX.md` + +7. **Suggest next step** + - Recommend `/qa` next + +## Tech Design Section Format (for feature specs) + +```markdown +## Tech Design + +### Classes +- `UserRepository`: handles user CRUD operations +- `UserService`: business logic for users + +### Database Schema +```sql +CREATE TABLE users ( + id INTEGER PRIMARY KEY, + email TEXT NOT NULL UNIQUE, + name TEXT NOT NULL, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP +); +``` + +### Implementation Order +1. Create migration +2. Implement UserRepository +3. Implement UserService +4. Write tests +``` + +## Rules + +- **PSR-12**: All code follows PSR-12 coding standard +- **Strict types**: All files start with `declare(strict_types=1);` +- **Parameterized queries**: Never interpolate user input into SQL +- **Portable SQL**: Works on SQLite, MariaDB, and PostgreSQL +- **Tests**: Write tests for all new classes/methods + +## Context Recovery + +If context is compacted: +1. Re-read feature spec +2. Check `git status` for uncommitted changes +3. Continue from next class/method to implement diff --git a/.opencode/skills/qa/SKILL.md b/.opencode/skills/qa/SKILL.md new file mode 100644 index 0000000..7b1c9c4 --- /dev/null +++ b/.opencode/skills/qa/SKILL.md @@ -0,0 +1,64 @@ +--- +name: qa +description: Tests features against acceptance criteria and performs security audit +category: development +--- + +# QA Engineer + +Tests a feature implementation against its acceptance criteria and performs a security audit. + +## When to Use + +``` +/qa features/PROJ-X-feature-name.md +``` + +## Skill Steps + +1. **Read context** + - Read the feature spec, especially: + - Acceptance criteria + - User stories + - Edge cases + +2. **Run tests** + - `npm test` - Unit/integration tests + - `npm run test:e2e` - E2E tests (requires dev server) + +3. **Manual testing** + - Start dev server: `npm run dev` + - Test each acceptance criterion manually + - Test edge cases + +4. **Security audit** + - Check for exposed secrets in code + - Verify auth is properly implemented + - Check input validation + +5. **Report results** + - Document what passed/failed + - List any bugs found + - Identify fixes needed + +6. **Fix failures** + - Fix any test failures + - Fix any acceptance criteria not met + - Re-run tests until all pass + +7. **Update tracking** + - Mark feature as "QA Passed" in `features/INDEX.md` + +## Rules + +- All acceptance criteria must pass +- All tests must pass (unit + E2E) +- No security vulnerabilities +- Fix all failures before declaring done + +## Context Recovery + +If context is compacted: +1. Re-read feature spec +2. Check which tests have passed +3. Continue from failures \ No newline at end of file diff --git a/.opencode/skills/requirements/SKILL.md b/.opencode/skills/requirements/SKILL.md new file mode 100644 index 0000000..80c86a7 --- /dev/null +++ b/.opencode/skills/requirements/SKILL.md @@ -0,0 +1,90 @@ +--- +name: requirements +description: Creates feature specs with user stories, acceptance criteria, and edge cases +category: development +--- + +# Requirements Engineer + +Creates detailed feature specifications for the AI Coding Starter Kit workflow. + +## When to Use + +Run this skill when you want to add a new feature to the project. It: +1. Reads the existing PRD to understand project context +2. Checks the feature index for the next available ID +3. Creates a feature spec with user stories, acceptance criteria, and edge cases +4. Updates the feature tracking index + +## Usage + +``` +/requirements +``` + +Then describe your feature idea. The skill will ask follow-up questions to clarify scope. + +## Skill Steps + +1. **Read project context** + - Read `docs/PRD.md` for project vision and constraints + - Read `features/INDEX.md` to see existing features and next PROJ-X ID + +2. **Clarify requirements** (interactive) + - Ask about target users + - Ask about core functionality + - Ask about MVP scope + - Ask about edge cases to handle + +3. **Create feature spec** + - Create file `features/PROJ-X-feature-name.md` + - Include: Feature name, ID, user stories, acceptance criteria, edge cases, dependencies + +4. **Update tracking** + - Update `features/INDEX.md` with new feature status (Pending) + +5. **Suggest next step** + - Recommend running `/architecture` next + +## Output + +- `features/PROJ-X-feature-name.md` - The feature specification +- Updated `features/INDEX.md` - Feature tracking updated + +## Feature Spec Format + +```markdown +# Feature: [Name] + +## ID +PROJ-X + +## Status +Pending + +## User Stories +- As a [role], I want [action], so that [benefit] +- ... + +## Acceptance Criteria +- [ ] Criterion 1 (testable) +- [ ] Criterion 2 (testable) + +## Edge Cases +- Case 1: description +- Case 2: description + +## Dependencies +- PROJ-Y (required first) +- ... + +## Tech Design +(Added later by /architecture skill) +``` + +## Context Recovery + +If context is compacted mid-task: +1. Re-read `docs/PRD.md` and `features/INDEX.md` +2. Check if feature spec was already created +3. Continue from where you left off \ No newline at end of file diff --git a/.shared/prompts/architecture.md b/.shared/prompts/architecture.md new file mode 100644 index 0000000..21f966f --- /dev/null +++ b/.shared/prompts/architecture.md @@ -0,0 +1,21 @@ +# Architecture Prompt Template + +Use this prompt structure for technical design: + +``` +Read the feature spec at features/PROJ-X-feature-name.md. +Design the technical architecture and add a Tech Design section to the spec file. + +Focus on: +- Component structure (for frontend) +- API design (endpoints, request/response shapes) +- Database schema (tables, relationships, indexes) +- Implementation order (what to build first, dependencies) +- Security considerations +- Tech stack decisions (libraries, patterns) +``` + +Example: +``` + exec "Read features/PROJ-1-login.md. Design the auth architecture: JWT vs sessions, database schema for users, password hashing approach, and implementation order." +``` \ No newline at end of file diff --git a/.shared/prompts/backend.md b/.shared/prompts/backend.md new file mode 100644 index 0000000..797f6f7 --- /dev/null +++ b/.shared/prompts/backend.md @@ -0,0 +1,23 @@ +# Backend Implementation Prompt Template + +Use this prompt structure for backend development: + +``` +Read features/INDEX.md and the feature spec at features/PROJ-X-feature-name.md. +Implement the backend components. + +Focus on: +- API endpoints (create, read, update, delete) +- Database queries (SQL, migrations) +- Business logic (validation, error handling) +- Authentication/Authorization if needed +- Rate limiting and security headers + +Write tests in the appropriate tests/ directory. +Follow the coding rules in .opencode/rules/ or .codex/config/project.md. +``` + +Example: +``` + exec "Read features/PROJ-1-login.md. Implement the login API: POST /auth/login endpoint, password verification, JWT generation. Add migration for users table. Write PHPUnit tests." +``` \ No newline at end of file diff --git a/.shared/prompts/deploy.md b/.shared/prompts/deploy.md new file mode 100644 index 0000000..552b671 --- /dev/null +++ b/.shared/prompts/deploy.md @@ -0,0 +1,27 @@ +# Deploy Prompt Template + +Use this prompt structure for deployment: + +``` +Read the feature spec at features/PROJ-X-feature-name.md. +Deploy the implemented feature to production. + +Steps: +1. Run build/lint/tests locally +2. Create git tag: v1.0.0-PROJ-X +3. Push to origin +4. Trigger deployment pipeline +5. Verify production URL works +6. Update feature spec with deployment status: + +## Deployment +**Status:** ✅ Deployed +**Deployed:** YYYY-MM-DD +**Production URL:** https://... +**Git Tag:** v1.0.0-PROJ-X +``` + +Example: +``` + exec "Deploy PROJ-1-login: run npm build, create tag v1.0.0-PROJ-1, push. Verify at https://www.example.com. Update feature spec." +``` \ No newline at end of file diff --git a/.shared/prompts/frontend.md b/.shared/prompts/frontend.md new file mode 100644 index 0000000..f887787 --- /dev/null +++ b/.shared/prompts/frontend.md @@ -0,0 +1,24 @@ +# Frontend Implementation Prompt Template + +Use this prompt structure for frontend development: + +``` +Read features/INDEX.md and the feature spec at features/PROJ-X-feature-name.md. +Implement the UI components. + +Focus on: +- Component structure (React/Vue components) +- State management +- Form handling and validation +- Responsive design +- Accessibility (a11y) +- Integration with backend API + +Write tests co-located next to source files (e.g., LoginForm.test.tsx next to LoginForm.tsx). +Follow the coding rules in .opencode/rules/frontend.md or .codex/config/project.md. +``` + +Example: +``` + exec "Read features/PROJ-1-login.md. Build the login form component: email/password inputs, validation, submit handler, error display. Use shadcn/ui components. Write tests." +``` \ No newline at end of file diff --git a/.shared/prompts/qa.md b/.shared/prompts/qa.md new file mode 100644 index 0000000..496de2c --- /dev/null +++ b/.shared/prompts/qa.md @@ -0,0 +1,28 @@ +# QA Prompt Template + +Use this prompt structure for quality assurance: + +``` +Read the feature spec at features/PROJ-X-feature-name.md. +Test the implementation against each acceptance criterion. + +Verify: +- [ ] Each acceptance criterion passes +- [ ] Edge cases handled gracefully +- [ ] Error messages are user-friendly +- [ ] No security vulnerabilities +- [ ] Performance is acceptable + +Document results in the feature spec: +- [x] AC-1: criterion passed +- [ ] AC-2: criterion failed (describe bug) + +Run: + +Fix any failures before marking as complete. +``` + +Example: +``` + exec "Test the login feature: verify email/password validation, test with wrong credentials, check rate limiting. Run npm test. Document results in features/PROJ-1-login.md." +``` \ No newline at end of file diff --git a/.shared/prompts/requirements.md b/.shared/prompts/requirements.md new file mode 100644 index 0000000..18c5ee3 --- /dev/null +++ b/.shared/prompts/requirements.md @@ -0,0 +1,25 @@ +# Requirements Prompt Template + +Use this prompt structure for creating feature specifications: + +``` +Read docs//doku/PRD.md to understand the project vision and constraints. +Read features/INDEX.md to see existing features and the next available PROJ-X ID. + +[Describe the feature idea clearly] + +Create a feature specification in features/PROJ-X-feature-name.md with: +- Feature name and ID +- User stories (3-5, with: As a [role], I want [action], so that [benefit]) +- Acceptance criteria (testable, specific) +- Edge cases (error handling, edge inputs, boundary conditions) +- Dependencies (other features required) +- Implementation notes (optional) + +Update features/INDEX.md with the new feature status. +``` + +Example: +``` + exec "Read docs/www.example.com/doku/PRD.md and features/INDEX.md. Create a feature spec for user authentication with email/password login, including: user stories for login/logout, acceptance criteria for valid/invalid credentials, edge cases for locked accounts and rate limiting." +``` \ No newline at end of file diff --git a/README.md b/README.md index f3edd7c..b3e87f3 100644 --- a/README.md +++ b/README.md @@ -9,41 +9,61 @@ skeleton/ ├── .git/ # Git Repository ├── .gitignore ├── AGENTS.md # opencode-cli Kontext -├── .opencode/ # opencode-cli Konfiguration (optional) -│ ├── settings.json +├── .opencode/ # OpenCode-Konfiguration +│ ├── config/ +│ │ └── project.md # Projekt-spezifische Config │ ├── rules/ -│ │ ├── general.md │ │ ├── backend.md +│ │ ├── database.md │ │ ├── frontend.md +│ │ ├── general.md +│ │ ├── php.md │ │ └── security.md -│ └── skills/ -│ └── help/SKILL.md +│ ├── skills/ # OpenCode Skills +│ │ ├── architecture/ +│ │ ├── backend/ +│ │ ├── deploy/ +│ │ ├── docs/ +│ │ ├── frontend/ +│ │ ├── php/ +│ │ ├── qa/ +│ │ └── requirements/ +│ └── prompts/ # Kopie von .shared/prompts +├── .codex/ # Codex-Konfiguration +│ ├── config/ +│ │ └── project.md # Projekt-spezifische Config +│ └── prompts/ # Kopie von .shared/prompts +├── .shared/ # Gemeinsame Ressourcen +│ └── prompts/ # Neutralisierte Prompts (tool-unabhängig) +│ ├── requirements.md +│ ├── architecture.md +│ ├── backend.md +│ ├── frontend.md +│ ├── qa.md +│ └── deploy.md ├── docs/ # Dokumentation pro Domain -│ ├── www.example.com/ # Docs für www.example.com -│ │ ├── doku/ # Technische Dokumentation -│ │ ├── planung/ # Planung, Meilensteine -│ │ └── todos/ # Aufgaben, TODOs -│ ├── api.example.com/ # Docs für api.example.com +│ ├── www.example.com/ │ │ ├── doku/ │ │ ├── planung/ │ │ └── todos/ -│ └── app.example.com/ # Docs für app.example.com +│ ├── api.example.com/ +│ │ ├── doku/ +│ │ ├── planung/ +│ │ └── todos/ +│ └── app.example.com/ │ ├── doku/ │ ├── planung/ │ └── todos/ -├── www/ # Webroot (deployed auf Server) -│ ├── www.example.com/ # www.example.com -│ │ └── public/ # Document Root -│ │ └── index.php -│ ├── api.example.com/ # api.example.com -│ │ └── public/ # Document Root -│ │ └── index.php -│ └── app.example.com/ # app.example.com -│ └── public/ # Document Root -│ └── index.php -├── features/ # Feature Specs (optional, von Starter Kit) +├── features/ # Feature Specs │ ├── INDEX.md -│ └── PROJ-X-*.md +│ └── README.md +├── www/ # Webroot (deployed auf Server) +│ ├── www.example.com/ +│ │ └── public/ +│ ├── api.example.com/ +│ │ └── public/ +│ └── app.example.com/ +│ └── public/ └── README.md ``` @@ -109,42 +129,43 @@ Skeleton ist flexibel — standardmäßig PHP mit SQLite, anpassbar je nach Proj ## Coding Starter Kits -Für AI-gestütztes Coding gibt es zwei spezialisierte Starter Kits die als Vorlage integriert werden können: +Die Starter Kits sind im Skeleton vereinheitlicht. Beide Tools nutzen dieselben Prompts aus `.shared/prompts/`. -### ai-coding-starter-kit-opencode (PHP) +### .shared/prompts/ -PHP-first Projekt-Kit für OpenCode mit SQLite-dev / MariaDB-Production Ansatz. +Enthält tool-unabhängige Prompts für alle Development-Phasen: -**Relevante Dateien die man übernehmen kann:** -- `OPENCODE.md` — Auto-geladenes Projekt-Kontext +| Prompt | Zweck | +|--------|-------| +| `requirements.md` | Feature Specs erstellen | +| `architecture.md` | Tech Design entwerfen | +| `backend.md` | Backend implementieren | +| `frontend.md` | UI bauen | +| `qa.md` | Testen & verifizieren | +| `deploy.md` | Produktiv setzen | + +### .opencode/ + +OpenCode-spezifische Konfiguration: +- `.opencode/config/project.md` — Projekt-Config - `.opencode/rules/*.md` — Coding Rules (PHP, Security, Database, etc.) -- `features/INDEX.md`, `features/PROJ-X-*.md` — Feature Tracking -- `docs/production/*.md` — Production Guidelines -- `composer.json` — PHP Dependencies +- `.opencode/skills/` — OpenCode Skills (autonome Agenten) +- `.opencode/prompts/` — Kopie von `.shared/prompts/` -```bash -# Beispiel: Regeln von opencode-kit übernehmen -git subtree add --prefix=.opencode https://git.shadow-land.de/madgerm/ai-coding-starter-kit-opencode.git .opencode -``` +### .codex/ -**Repo:** https://git.shadow-land.de/madgerm/ai-coding-starter-kit-opencode +Codex-spezifische Konfiguration: +- `.codex/config/project.md` — Projekt-Config +- `.codex/prompts/` — Kopie von `.shared/prompts/` -### ai-coding-starter-kit-codex (TypeScript/Next.js) +### Eigene Kits behalten oder löschen? -TypeScript/Next.js Projekt-Kit mit Supabase. +Die ursprünglichen Starter Kits können gelöscht werden: -**Relevante Dateien die man übernehmen kann:** -- `features/INDEX.md`, `features/PROJ-X-*.md` — Feature Tracking -- `docs/production/*.md` — Production Guidelines -- `tailwind.config.ts`, `next.config.ts` — Framework Config -- `.opencode/rules/` — Coding Rules +- ~~https://git.shadow-land.de/madgerm/ai-coding-starter-kit-opencode~~ +- ~~https://git.shadow-land.de/madgerm/ai-coding-starter-kit-codex~~ -```bash -# Beispiel: Features-Struktur übernehmen -git subtree add --prefix=features https://git.shadow-land.de/madgerm/ai-coding-starter-kit-codex.git features -``` - -**Repo:** https://git.shadow-land.de/madgerm/ai-coding-starter-kit-codex +Das Skeleton enthält alles was beide brauchen. ## Lizenz diff --git a/features/INDEX.md b/features/INDEX.md new file mode 100644 index 0000000..d2dcb46 --- /dev/null +++ b/features/INDEX.md @@ -0,0 +1,25 @@ +# Feature Index + +Tracks all features in the project. Updated by each skill. + +| ID | Feature | Status | Spec | +|----|---------|--------|------| +| PROJ-1 | User Authentication | Pending | [Spec](PROJ-1-user-auth.md) | + + + +--- + +**Status meanings:** +- `Pending` — Requirements written, ready for development +- `Designed` — Architecture completed +- `Implemented` — Code written, tests passing +- `QA Passed` — All acceptance criteria met +- `Deployed` — Live in production + +**Workflow:** +1. `/requirements` → creates spec → status: Pending +2. `/architecture` → adds tech design → status: Designed +3. `/php` → implements code → status: Implemented +4. `/qa` → tests pass → status: QA Passed +5. `/deploy` → deployed → status: Deployed diff --git a/features/README.md b/features/README.md new file mode 100644 index 0000000..e1f55cb --- /dev/null +++ b/features/README.md @@ -0,0 +1,112 @@ +# Feature Specifications + +Dieser Ordner enthält detaillierte Feature Specs vom Requirements Engineer. + +## Naming Convention +`PROJ-X-feature-name.md` + +Beispiele: +- `PROJ-1-user-authentication.md` +- `PROJ-2-kanban-board.md` +- `PROJ-3-file-attachments.md` + +## Was gehört in eine Feature Spec? + +### 1. User Stories +Beschreibe, was der User tun möchte: +```markdown +Als [User-Typ] möchte ich [Aktion] um [Ziel zu erreichen] +``` + +### 2. Acceptance Criteria +Konkrete, testbare Kriterien: +```markdown +- [ ] User kann Email + Passwort eingeben +- [ ] Passwort muss mindestens 8 Zeichen lang sein +- [ ] Nach Registration wird User automatisch eingeloggt +``` + +### 3. Edge Cases +Was passiert bei unerwarteten Situationen: +```markdown +- Was passiert bei doppelter Email? +- Was passiert bei Netzwerkfehler? +- Was passiert bei gleichzeitigen Edits? +``` + +### 4. Tech Design (vom Solution Architect) +```markdown +## Database Schema +CREATE TABLE tasks (...); + +## Component Architecture +ProjectDashboard +├── ProjectList +│ └── ProjectCard +``` + +### 5. QA Test Results (vom QA Engineer) +Am Ende des Feature-Dokuments fügt QA die Test-Ergebnisse hinzu: +```markdown +--- + +## QA Test Results + +**Tested:** 2026-01-12 +**App URL:** http://localhost:3000 + +### Acceptance Criteria Status +- [x] AC-1: User kann Email + Passwort eingeben +- [x] AC-2: Passwort mindestens 8 Zeichen +- [ ] ❌ BUG: Doppelte Email wird nicht abgelehnt + +### Bugs Found +**BUG-1: Doppelte Email-Registrierung** +- **Severity:** High +- **Steps to Reproduce:** 1. Register with email, 2. Try again with same email +- **Expected:** Error message +- **Actual:** Silent failure +``` + +### 6. Deployment Status (vom DevOps Engineer) +```markdown +--- + +## Deployment + +**Status:** ✅ Deployed +**Deployed:** 2026-01-13 +**Production URL:** https://your-app.vercel.app +**Git Tag:** v1.0.0-PROJ-1 +``` + +## Workflow + +1. **Requirements Engineer** erstellt Feature Spec +2. **User** reviewed Spec und gibt Feedback +3. **Solution Architect** fügt Tech-Design hinzu +4. **User** approved finales Design +5. **Frontend/Backend Devs** implementieren (dokumentiert via Git Commits) +6. **QA Engineer** testet und fügt Test-Ergebnisse zum Feature-Dokument hinzu +7. **DevOps** deployed und fügt Deployment-Status zum Feature-Dokument hinzu + +## Status-Tracking + +Feature-Status wird direkt im Feature-Dokument getrackt: +```markdown +# PROJ-1: Feature Name + +**Status:** 🔵 Planned | 🟡 In Progress | ✅ Deployed +**Created:** 2026-01-12 +**Last Updated:** 2026-01-12 +``` + +**Status-Bedeutung:** +- 🔵 Planned – Requirements sind geschrieben, ready for development +- 🟡 In Progress – Wird gerade gebaut +- ✅ Deployed – Live in Production + +**Git als Single Source of Truth:** +- Alle Implementierungs-Details sind in Git Commits +- `git log --grep="PROJ-1"` zeigt alle Änderungen für dieses Feature +- Keine separate FEATURE_CHANGELOG.md nötig!