From 70f3a494eecd9d6329897aa1ed3f5fe60266e7d1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 4 Jan 2026 04:31:01 +0000
Subject: [PATCH] docs: update README and CONTRIBUTING with new development
 tools

- Add Quick Start section to README with make commands
- Add Development Tools section to CONTRIBUTING
- Link to new documentation guides (QUICK_START.md, WORKFLOW_GUIDE.md)
- Update development workflow section with modern tooling
- Add clear onboarding path for new contributors

Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com>
---
 CONTRIBUTING.md | 31 +++++++++++++++++++++++
 README.md       | 65 ++++++++++++++++++++++++++++++-------------------
 2 files changed, 71 insertions(+), 25 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e461eed..8aaa234 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -48,6 +48,37 @@ Contributors are expected to:
 * Have a working understanding of Joomla template structure.
 * Be familiar with Git and GitHub pull request workflows.
 * Review repository governance documents prior to submitting changes.
+* Set up the development environment using the provided tools.
+
+### Quick Setup
+
+For first-time contributors:
+
+```bash
+# Clone the repository
+git clone https://github.com/mokoconsulting-tech/moko-cassiopeia.git
+cd moko-cassiopeia
+
+# Run development setup
+make dev-setup
+
+# Install Git hooks (optional but recommended)
+./scripts/git/install-hooks.sh
+```
+
+See [docs/QUICK_START.md](./docs/QUICK_START.md) for detailed setup instructions.
+
+## Development Tools
+
+The repository provides several tools to streamline development:
+
+* **Makefile**: Common development tasks (`make help` to see all commands)
+* **Pre-commit Hooks**: Automatic local validation before commits
+* **VS Code Tasks**: Pre-configured tasks for common operations
+* **Validation Scripts**: Located in `scripts/validate/`
+* **CI/CD Workflows**: Automated testing and deployment
+
+Run `make validate-required` before submitting PRs to catch common issues early.
 
 ## Contribution Workflow
 
diff --git a/README.md b/README.md
index 2f80254..d5c2e24 100644
--- a/README.md
+++ b/README.md
@@ -134,6 +134,44 @@ If upgrading from a prior version, Joomla will safely overwrite files
 
 For developers and contributors working on the moko-cassiopeia template:
 
+### Quick Start for Developers
+
+Get started in minutes:
+
+```bash
+# Setup development environment
+make dev-setup
+
+# Validate code
+make validate-required
+
+# Check code quality
+make quality
+
+# Create distribution package
+make package
+
+# Install Git hooks (optional but recommended)
+./scripts/git/install-hooks.sh
+```
+
+**New to the project?** See [Quick Start Guide](./docs/QUICK_START.md) for a 5-minute walkthrough.
+
+### Development Resources
+
+- **[Quick Start Guide](./docs/QUICK_START.md)** - Get up and running in 5 minutes
+- **[Workflow Guide](./docs/WORKFLOW_GUIDE.md)** - Complete workflow reference with examples
+- **[Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md)** - Testing, quality checks, and deployment
+- **[Scripts Documentation](./scripts/README.md)** - Available automation scripts
+- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute
+
+### Available Tools
+
+- **Makefile**: Run `make help` to see all available commands
+- **Pre-commit Hooks**: Automatic validation before commits
+- **VS Code Tasks**: Pre-configured development tasks
+- **GitHub Actions**: Automated CI/CD pipelines
+
 ### Joomla Development Workflows
 
 Comprehensive Joomla-aware development tools and workflows are available:
@@ -141,32 +179,9 @@ Comprehensive Joomla-aware development tools and workflows are available:
 - **Extension Packaging** - Create distributable ZIP packages
 - **PHP Quality Checks** - PHPStan and PHP_CodeSniffer with Joomla standards
 - **Automated Testing** - Codeception framework with multiple Joomla versions
-- **CI/CD Pipelines** - GitHub Actions for testing and deployment
+- **CI/CD Pipelines** - GitHub Actions with caching for faster builds
 
-See the [Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md) for:
-- Setup instructions for local development
-- Running tests and quality checks
-- Creating release packages
-- Deployment workflows
-- CI/CD pipeline details
-
-### Quick Start for Developers
-
-```bash
-# Validate code
-./scripts/validate/php_syntax.sh
-./scripts/validate/manifest.sh
-
-# Create distribution package
-./scripts/release/package_extension.sh dist 3.5.0
-
-# Run tests (requires Codeception)
-codecept run
-
-# Check code quality (requires PHPStan/PHPCS)
-phpstan analyse --configuration=phpstan.neon
-phpcs --standard=phpcs.xml
-```
+Run `make help` to see all available development commands.
 
 ## Changelog