Skip to content

CLAUDE.md

Latest commit

 

History

History
78 lines (55 loc) · 3.34 KB

CLAUDE.md

File metadata and controls

78 lines (55 loc) · 3.34 KB

Marko Framework

Marko is a modular PHP 8.5+ framework combining Magento's extensibility with Laravel's developer experience.

Core Principles

  1. Loud errors - No silent failures, helpful messages
  2. Explicit over implicit - No magic, everything discoverable
  3. Pragmatically opinionated - Guide toward better patterns, grounded in real-world needs
  4. True modularity - Interface/implementation split, clean boundaries
  5. No pseudo-functionality - Don't build fake features to demonstrate concepts; only build real functionality when core supports it. If there's nothing meaningful to build, build nothing.

Commands

# Run tests (fast — excludes slow destructive integration tests)
composer test

# Run all tests including destructive integration tests
composer test:all

# Run with coverage
./vendor/bin/pest -c phpunit.xml --parallel --exclude-group=integration-destructive --coverage --min=80

# Lint (check)
./vendor/bin/phpcs

# Lint (fix)
./vendor/bin/php-cs-fixer fix

Key Conventions

  • Branch naming - all branches use feature/{name} format, regardless of change type (fix, feature, refactor, docs, etc.). Never use fix/, chore/, or other prefixes
  • No hardcoded versions in composer.json - never add "version" to package composer.json files; let Composer infer from the branch
  • Constructor property promotion - always use it
  • Strict types - every file needs declare(strict_types=1)
  • No magic methods - be explicit
  • No final classes - blocks Preferences (extensibility)
  • readonly - use when appropriate for immutability, not as blanket rule
  • Type declarations - required on all parameters, returns, properties

Feature Development

For simple fixes and quick changes, use TDD (when at all possible).

For any feature or request beyond simple ones, use the hcf:plan-create skill to trigger the autonomous development workflow. NEVER use Claude Code's built-in plan mode. After writing a plan, ask user if they would like to execute it. Also provide the command to run it later with the hcf:plan-orchestrate skill.

Use this workflow for new features, multi-file changes, or anything requiring multiple steps or tests.

Project Overview

@.claude/project-overview.md

Architecture

@.claude/architecture.md

Reviewing PRs

When reviewing or merging a pull request, read .claude/pr-review-process.md first. It has the full review workflow, code-quality checklist, package-PR-specific checks (module.php minimalism, required docs page, composer.json conventions, cross-cutting updates), and the merge policy. Not auto-loaded — pull it into context only when actively reviewing.

Detailed Configuration

Project configuration files are in .claude/:

  • project-overview.md — Project identity and tech stack
  • architecture.md — Technical patterns and directory structure
  • testing.md — Test configuration, TDD workflow, and patterns
  • code-standards.md — Coding conventions and style rules
  • pr-review-process.md — PR review workflow, checklist, and merge policy
  • module-development.md — Building new packages/modules
  • sibling-modules.md — Naming and conventions for driver packages
  • pipeline.md — Post-plan and post-implementation agent pipeline
  • release-process.md — Release workflow