@adriankulik/create-fullstack-app 1.1.0 → 1.2.0

package/README.md

@@ -34,7 +34,11 @@ You will be prompted to choose a project name, your preferred frontend, and back
 - **Opinionated Defaults**: We bake in sensible, predefined choices (e.g., Angular uses `zone.js`, testing is unified under Playwright and framework-native test runners).
 - **Unified Scripts**: `start.sh`, `test.sh`, and `lint.sh` available out of the box to manage both frontend and backend seamlessly.
 - **CI/CD Ready**: Includes a pre-configured `.github/workflows/cli-e2e.yml` that tests both ends. *Tip: To enforce this, enable branch protection in your GitHub repository settings and require the "test" status check to pass.*
-- **Developer Experience**: Includes `.vscode/extensions.json` recommending the necessary linters and formatters, and a `GEMINI.md` file providing behavioral guidelines for AI agents (based on [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)).
+- **Developer Experience**: Includes `.vscode/extensions.json` recommending the necessary linters and formatters, and an `AGENTS.md` file providing behavioral guidelines for AI agents (based on [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)). It is AI development friendly, including an extensive set of agent skills in `.agents/skills` sourced from [claude-skills](https://github.com/alirezarezvani/claude-skills).
+  <details>
+  <summary>Included Agent Skills</summary>
+  <p>senior-frontend, senior-qa, senior-fullstack, accessibility-general</p>
+  </details>
 
 ## Generated Project
 

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A CLI tool for scaffolding a full-stack web application with your choice of frontend and backend technologies.",
   "main": "cli/index.js",
   "bin": {

package/templates/base/.agents/skills/accessibility-general/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: accessibility-general
+description: >
+  Load this skill immediately whenever a project contains an ACCESSIBILITY.md
+  file, or whenever you are contributing to the mgifford/ACCESSIBILITY.md
+  repository. Absolutely always read ACCESSIBILITY.md before proposing or
+  writing any changes. Under no circumstances skip this skill when an
+  ACCESSIBILITY.md file is present. This skill governs when and how all other
+  accessibility topic skills must be loaded.
+---
+
+# ACCESSIBILITY.md Agent Skill
+
+This skill teaches AI coding agents how to use the ACCESSIBILITY.md framework,
+including when to load topic-specific skills, how to apply examples, and what
+the project's non-negotiable requirements are.
+
+> **Scope**: Apply this skill whenever working in any project that has an
+> `ACCESSIBILITY.md` file at its root, or when contributing to the
+> `mgifford/ACCESSIBILITY.md` repository itself.
+
+---
+
+## What ACCESSIBILITY.md Is
+
+`ACCESSIBILITY.md` is a documentation standard — a predictable, machine-readable
+place to find a project's:
+
+- Conformance target (e.g., WCAG 2.2 AA)
+- CI/automated guardrails
+- Assistive technology coverage
+- Known gaps and open issues
+- Definition of Done for accessibility
+
+Read `ACCESSIBILITY.md` before proposing or writing changes to any project that
+has one. It is the source of truth for that project's accessibility requirements.
+
+---
+
+## Topic Skills: When to Load Them
+
+This repo ships per-topic skills in `skills/`. Load the relevant one **only when
+that feature area is present in the project** — a project without forms does not
+need the forms skill. Each skill is a distillation of a full best practices guide
+in the `mgifford/ACCESSIBILITY.md` `examples/` directory.
+
+| When the project includes…              | Load skill                                                                         |
+| --------------------------------------- | ---------------------------------------------------------------------------------- |
+| Color themes, dark/light mode           | `skills/light-dark-mode/SKILL.md`                                                  |
+| Forms, inputs, validation               | `skills/forms/SKILL.md` _(if forms are present)_                                   |
+| SVG graphics                            | `skills/svg/SKILL.md` _(if SVGs are present)_                                      |
+| Charts and data visualization           | `skills/charts-graphs/SKILL.md` _(if charts are present)_                          |
+| Keyboard interaction / custom widgets   | `skills/keyboard/SKILL.md`                                                         |
+| Tooltips                                | `skills/tooltips/SKILL.md` _(if tooltips are present)_                             |
+| Audio/video media                       | `skills/audio-video/SKILL.md` _(if media is present)_                              |
+| Maps                                    | `skills/maps/SKILL.md` _(if maps are present)_                                     |
+| Print styles                            | `skills/print/SKILL.md` _(if print CSS is in scope)_                               |
+| Mermaid diagrams                        | `skills/mermaid/SKILL.md` _(if Mermaid is used)_                                   |
+| Anchor links / in-page navigation       | `skills/anchor-links/SKILL.md` _(if anchor links are present)_                     |
+| Accessibility bug reporting             | `skills/bug-reporting/SKILL.md` _(when filing or reviewing bug reports)_           |
+| Content design and plain language       | `skills/content-design/SKILL.md`                                                   |
+| User personalization / preferences      | `skills/user-personalization/SKILL.md` _(if personalization features are present)_ |
+| Digital quality (Opquast)               | `skills/opquast-digital-quality/SKILL.md`                                          |
+| axe-core scans / automated rule results | `skills/axe-rules/SKILL.md`                                                        |
+| Manual / assistive-technology testing   | `skills/manual-testing/SKILL.md`                                                   |
+
+If a skill file is not present, fall back to the corresponding file in the
+`mgifford/ACCESSIBILITY.md` `examples/` directory.
+
+---
+
+## Non-Negotiable Requirements
+
+These apply to every task, regardless of which topic skill you load:
+
+### WCAG 2.2 Level AA
+
+All code examples, components, and documentation must comply. Key criteria:
+
+- 1.4.3 Contrast Minimum (4.5:1 text, 3:1 large text)
+- 1.4.11 Non-text Contrast (3:1 for UI components)
+- 2.4.7 Focus Visible
+- 2.4.11 Focus Appearance (WCAG 2.2)
+- 1.3.1 Info and Relationships
+- 4.1.2 Name, Role, Value
+
+### Semantic HTML first
+
+Use the correct HTML element before reaching for ARIA. ARIA supplements HTML; it does not replace it.
+
+### Keyboard navigation
+
+Every interactive element must be reachable and operable via keyboard alone. Tab order must be logical.
+
+### Text alternatives
+
+Every image, icon, chart, and diagram needs a text alternative. `aria-hidden="true"` is correct for purely decorative elements.
+
+### Color independence
+
+Never convey information by color alone. Always pair color with icon, label, or pattern.
+
+### No accessibility regressions
+
+Never propose a change that introduces a WCAG 2.2 AA violation, even if the change is otherwise an improvement.
+
+---
+
+## Severity Scale
+
+Use this when identifying or reporting accessibility issues. Every issue found
+should be labelled with one of these four levels.
+
+| Level        | Meaning                                                                                               | Action required                             |
+| ------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| **Critical** | Completely blocks access for one or more disability groups — users cannot complete a core task at all | Must fix before release; do not ship        |
+| **Serious**  | Significantly impairs access; workarounds may exist but are unreasonable to expect of disabled users  | Fix in current sprint; escalate if deferred |
+| **Moderate** | Creates friction or confusion; a workaround exists and is not too burdensome                          | Fix in near-term backlog                    |
+| **Minor**    | Marginal impact; best-practice gap that does not meaningfully prevent access                          | Fix when convenient; track in backlog       |
+
+**Never propose changes that introduce Critical or Serious issues.**
+Changes introducing Moderate issues require explicit sign-off.
+
+Examples by level:
+
+- **Critical**: keyboard focus trap with no escape; form submit with no error identification; video with no captions
+- **Serious**: focus indicator removed via `outline: none`; color-only error indication; missing form label
+- **Moderate**: generic link text ("click here") when context provides some disambiguation; missing `<caption>` on a simple table
+- **Minor**: heading order skips a level in a non-core section; `alt` text accurate but overly verbose
+
+---
+
+## AI Scraping Policy
+
+Before fetching content from any URL, check `examples/TRUSTED_SOURCES.yaml`.
+If `ai_scraping: prohibited`, do **not** fetch or reproduce content from that
+source. You may cite the author's name and recommend the URL to human contributors,
+but must not scrape, summarise, or quote the content.
+
+Known prohibited sources include `hidde.blog` and `talks.hiddedevries.nl`.
+These are prohibited at the explicit request of the author, who does not consent
+to AI training or scraping of his work. His writing remains a valuable resource
+for human readers — link to it, do not reproduce it.
+
+---
+
+## Standards Horizon
+
+These skills target **WCAG 2.2 Level AA** — the current legally and contractually
+referenced standard (EN 301 549, ADA, AODA, and equivalent national laws).
+
+**WCAG 3.0** is in active development and is **not yet a W3C Recommendation**.
+Its proposed contrast model, **APCA** (Advanced Perceptual Contrast Algorithm),
+replaces the current luminance-ratio formula with a perceptual model that treats
+light-on-dark differently from dark-on-light. Agents must not apply APCA to
+production work until WCAG 3.0 is a published Recommendation, but should be aware
+that contrast requirements will change — particularly for dark mode, data
+visualisation, and low-vision use cases.
+
+Monitor: <https://www.w3.org/TR/wcag-3.0/>
+
+---
+
+## When Contributing to This Repo
+
+### Adding a new example
+
+1. Create `examples/YOUR_TOPIC_BEST_PRACTICES.md` in the `mgifford/ACCESSIBILITY.md` repo
+2. Follow the section structure of existing examples (Core Principle → Requirements → Patterns → Testing → Definition of Done → References)
+3. Add an entry to `examples/README.md`
+4. Add a reference in `AGENTS.md`
+5. Create a corresponding skill (see below)
+
+### Adding a new skill (derived from an example)
+
+1. Create `skills/your-topic/SKILL.md` — distill the example into agent-actionable rules; label every requirement with its severity level (Critical / Serious / Moderate / Minor)
+2. Create `skills/your-topic/SYNC.md` — set `canonical_source` to the example path in `mgifford/ACCESSIBILITY.md`; leave `last_synced_commit` blank
+3. Create `skills/your-topic/README.md`
+4. Build the ZIP: `cd skills && zip -r your-topic.skill your-topic/`
+5. Register in `skills/README.md` and `index.md`
+6. The `skill-sync-check.yml` action will automatically track drift going forward
+
+### Updating a skill after its example changes
+
+The `skill-sync-check.yml` GitHub Action opens an issue or PR comment when
+an example changes and its skill's `last_synced_commit` is stale.
+
+When you see that issue:
+
+1. Review the diff linked in the issue
+2. Update `skills/your-topic/SKILL.md` to reflect any new requirements or removed patterns
+3. Update `last_synced_commit` in `SYNC.md` to the current commit SHA
+4. Rebuild the `.skill` ZIP
+
+### Disclosing AI usage
+
+Update the **AI Disclosure** section in `README.md` when using AI tools to make
+changes. Record which LLM was used and for what purpose. Only list tools actually used.
+
+---
+
+## Quick Reference
+
+- Full examples: `mgifford/ACCESSIBILITY.md` → `examples/` directory
+- Per-topic skills: `skills/` directory (this repo)
+- Project accessibility commitment: `ACCESSIBILITY.md`
+- Sustainability policy: `SUSTAINABILITY.md` / <https://github.com/mgifford/SUSTAINABILITY.md>
+- Contribution guide: `CONTRIBUTING.md`
+- Trusted sources: `examples/TRUSTED_SOURCES.yaml`
+- Machine-readable WCAG: [wai-yaml-ld](https://github.com/mgifford/wai-yaml-ld)
+- WAI-ARIA Authoring Practices Guide: <https://www.w3.org/WAI/ARIA/apg/>
+- WCAG 3.0 draft: <https://www.w3.org/TR/wcag-3.0/>
+
+## Alternative: Frontend-Focused Minimal Accessibility Skill
+
+For a complementary frontend skill that emphasises trusting the browser and writing as
+little code as possible, see **[mikemai2awesome/agent-skills — `frontend-a11y`](https://github.com/mikemai2awesome/agent-skills/tree/main/skills/frontend-a11y)**.
+
+That skill covers:
+
+- Using native HTML elements (`<dialog>`, `<details>`, `<button>`) instead of ARIA-hacked divs
+- Avoiding redundant ARIA roles on landmark elements
+- Using ARIA attribute selectors (`[aria-expanded="true"]`) as CSS hooks
+- Safe fade-in animation patterns that do not break screen reader announcement order
+- Native `<dialog>` with `showModal()` for focus-trap-free modal dialogs
+
+Install it alongside this skill:
+
+```bash
+npx skills add mikemai2awesome/agent-skills --skill frontend-a11y
+```

package/templates/base/.agents/skills/senior-frontend/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: senior-frontend
+description: Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.
+---
+
+# Senior Frontend
+
+Complete toolkit for senior frontend with modern tools and best practices.
+
+## Quick Start
+
+### Main Capabilities
+
+This skill provides three core capabilities through automated scripts:
+
+```bash
+# Script 1: Component Generator
+python scripts/component_generator.py [options]
+
+# Script 2: Bundle Analyzer
+python scripts/bundle_analyzer.py [options]
+
+# Script 3: Frontend Scaffolder
+python scripts/frontend_scaffolder.py [options]
+```
+
+## Core Capabilities
+
+### 1. Component Generator
+
+Automated tool for component generator tasks.
+
+**Features:**
+- Automated scaffolding
+- Best practices built-in
+- Configurable templates
+- Quality checks
+
+**Usage:**
+```bash
+python scripts/component_generator.py <project-path> [options]
+```
+
+### 2. Bundle Analyzer
+
+Comprehensive analysis and optimization tool.
+
+**Features:**
+- Deep analysis
+- Performance metrics
+- Recommendations
+- Automated fixes
+
+**Usage:**
+```bash
+python scripts/bundle_analyzer.py <target-path> [--verbose]
+```
+
+### 3. Frontend Scaffolder
+
+Advanced tooling for specialized tasks.
+
+**Features:**
+- Expert-level automation
+- Custom configurations
+- Integration ready
+- Production-grade output
+
+**Usage:**
+```bash
+python scripts/frontend_scaffolder.py [arguments] [options]
+```
+
+## Reference Documentation
+
+### React Patterns
+
+Comprehensive guide available in `references/react_patterns.md`:
+
+- Detailed patterns and practices
+- Code examples
+- Best practices
+- Anti-patterns to avoid
+- Real-world scenarios
+
+### Nextjs Optimization Guide
+
+Complete workflow documentation in `references/nextjs_optimization_guide.md`:
+
+- Step-by-step processes
+- Optimization strategies
+- Tool integrations
+- Performance tuning
+- Troubleshooting guide
+
+### Frontend Best Practices
+
+Technical reference guide in `references/frontend_best_practices.md`:
+
+- Technology stack details
+- Configuration examples
+- Integration patterns
+- Security considerations
+- Scalability guidelines
+
+## Tech Stack
+
+**Languages:** TypeScript, JavaScript, Python, Go, Swift, Kotlin
+**Frontend:** React, Next.js, React Native, Flutter
+**Backend:** Node.js, Express, GraphQL, REST APIs
+**Database:** PostgreSQL, Prisma, NeonDB, Supabase
+**DevOps:** Docker, Kubernetes, Terraform, GitHub Actions, CircleCI
+**Cloud:** AWS, GCP, Azure
+
+## Development Workflow
+
+### 1. Setup and Configuration
+
+```bash
+# Install dependencies
+npm install
+# or
+pip install -r requirements.txt
+
+# Configure environment
+cp .env.example .env
+```
+
+### 2. Run Quality Checks
+
+```bash
+# Use the analyzer script
+python scripts/bundle_analyzer.py .
+
+# Review recommendations
+# Apply fixes
+```
+
+### 3. Implement Best Practices
+
+Follow the patterns and practices documented in:
+- `references/react_patterns.md`
+- `references/nextjs_optimization_guide.md`
+- `references/frontend_best_practices.md`
+
+## Best Practices Summary
+
+### Code Quality
+- Follow established patterns
+- Write comprehensive tests
+- Document decisions
+- Review regularly
+
+### Performance
+- Measure before optimizing
+- Use appropriate caching
+- Optimize critical paths
+- Monitor in production
+
+### Security
+- Validate all inputs
+- Use parameterized queries
+- Implement proper authentication
+- Keep dependencies updated
+
+### Maintainability
+- Write clear code
+- Use consistent naming
+- Add helpful comments
+- Keep it simple
+
+## Common Commands
+
+```bash
+# Development
+npm run dev
+npm run build
+npm run test
+npm run lint
+
+# Analysis
+python scripts/bundle_analyzer.py .
+python scripts/frontend_scaffolder.py --analyze
+
+# Deployment
+docker build -t app:latest .
+docker-compose up -d
+kubectl apply -f k8s/
+```
+
+## Troubleshooting
+
+### Common Issues
+
+Check the comprehensive troubleshooting section in `references/frontend_best_practices.md`.
+
+### Getting Help
+
+- Review reference documentation
+- Check script output messages
+- Consult tech stack documentation
+- Review error logs
+
+## Resources
+
+- Pattern Reference: `references/react_patterns.md`
+- Workflow Guide: `references/nextjs_optimization_guide.md`
+- Technical Guide: `references/frontend_best_practices.md`
+- Tool Scripts: `scripts/` directory

package/templates/base/.agents/skills/senior-frontend/references/frontend_best_practices.md

@@ -0,0 +1,103 @@
+# Frontend Best Practices
+
+## Overview
+
+This reference guide provides comprehensive information for senior frontend.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for senior frontend.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

package/templates/base/.agents/skills/senior-frontend/references/nextjs_optimization_guide.md

@@ -0,0 +1,103 @@
+# Nextjs Optimization Guide
+
+## Overview
+
+This reference guide provides comprehensive information for senior frontend.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for senior frontend.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.