Add CLAUDE.md and AGENTS.md with codebase review and improvement roadmap#28
Merged
Add CLAUDE.md and AGENTS.md with codebase review and improvement roadmap#28
Conversation
Thorough review of all 42 source files and 18 test files to create project context (CLAUDE.md) and agent instructions (AGENTS.md). CLAUDE.md covers: architecture, namespace map, state machine, key contracts, conventions, builder patterns, and CI/CD pipeline. AGENTS.md covers: code review checklist, testing gaps, implementation patterns, and a prioritized improvement roadmap identifying 16 issues including unimplemented timeouts, missing retry logic, broken compensation/saga pattern, and Laravel helper coupling in a framework-agnostic package. https://claude.ai/code/session_013CdFJtmtMmSqBZFwdrmicG
…s, clean API, add event spy Phase 1 — Remove Laravel coupling: - Add Support\Arr helper for dot-notation array access - Replace data_get() calls in Step and WorkflowDefinition with Arr::get() - Remove getNestedValue() from WorkflowDefinition - Fix HttpAction to use curl instead of Laravel Http facade - Remove Laravel-specific PHPStan suppressions Phase 3 — Normalize event naming: - Rename WorkflowStarted → WorkflowStartedEvent - Rename WorkflowCancelled → WorkflowCancelledEvent - Standardize constructors to accept WorkflowInstance Phase 4 — Clean up duplicate API methods: - Remove getWorkflow() (duplicate of getInstance()) - Remove listWorkflows() (duplicate of getInstances()) - Add WorkflowState enum conversion to getInstances() Phase 7 — Add SpyEventDispatcher: - Create tests/Support/SpyEventDispatcher for event verification - Add EventDispatchTest integration tests - Add ArrTest unit tests https://claude.ai/code/session_013CdFJtmtMmSqBZFwdrmicG
…e enforcement Phase 2 — Deduplicate condition evaluation: - Extract ConditionEvaluator to Support namespace - Both Step and WorkflowDefinition delegate to it - Throw on unparseable conditions instead of silently passing Phase 5 — Retry logic: - Add executeActionWithRetry() to Executor with exponential backoff - Dispatch StepRetriedEvent on each retry attempt - Respects Step::getRetryAttempts() configuration Phase 6 — Timeout enforcement: - Add executeWithTimeout() using pcntl_alarm (graceful fallback) - Add Timeout helper for parsing duration strings (30s, 5m, 2h, 1d) - Wrap action execution with timeout in Executor Phase 8 — State transition enforcement: - WorkflowInstance::setState() now validates via canTransitionTo() - Add PENDING→FAILED and PAUSED→FAILED transitions - Executor handles PAUSED→RUNNING and WAITING→RUNNING on resume - WorkflowEngine::cancel() guards against terminal states Additional fixes: - Replace ALL remaining data_get/data_set/class_basename calls (WorkflowContext, ActionResult, ConditionAction, SimpleWorkflow, ActionNotFoundException, StepExecutionException) - Add Arr::classBasename() helper - Clean up stale PHPStan ignore patterns - Fix DocumentApproval test conditions to proper format CI: 93 tests, 224 assertions, all green. PHPStan level 6 clean. https://claude.ai/code/session_013CdFJtmtMmSqBZFwdrmicG
Sync documentation with actual codebase after recent improvements: - Update file counts (46 src, 25 test files) and test stats (93 tests, 224+ assertions) - Fix Quick Start code examples to use the actual WorkflowEngine API - Add complete namespace map with all classes including DefinitionParser, ActionResolver, StepRetriedEvent, ConditionEvaluator, Arr, Timeout - Document enforced state transitions with valid transition rules - Update StorageAdapter example with all 6 interface methods - Fix EventDispatcher example with correct class names and modern PHP syntax - Add debug() to Logger example, matching actual contract - Document quick template for documentApproval() - Add new quality standards: architecture tests, state transition validation, CI matrix https://claude.ai/code/session_013CdFJtmtMmSqBZFwdrmicG
Add back documentation for PHP 8 attributes (#[Retry], #[Timeout], #[Condition], #[WorkflowStep]) that were inadvertently removed. These are real features using readonly classes with native PHP attributes. https://claude.ai/code/session_013CdFJtmtMmSqBZFwdrmicG
- Standardize WorkflowCompletedEvent and WorkflowFailedEvent to use
`final readonly class` with constructor promotion, matching all other
event classes. Added helper methods (getWorkflowId, getWorkflowName,
getErrorMessage) for consistency.
- README improvements:
- Remove broken /docs link that pointed to non-existent directory
- Document SimpleWorkflow helper with usage examples
- Document getInstances() filter options (state, definition_name,
created_after, created_before, limit, offset)
- Document getProgress() and getStatusSummary() on WorkflowInstance
- Add built-in actions table (LogAction, ConditionAction, etc.)
- Add WorkflowState helper methods section (isActive, color, icon, etc.)
- Clarify PHP 8.3+ attributes are metadata annotations, not yet
auto-parsed by the engine at runtime
https://claude.ai/code/session_013CdFJtmtMmSqBZFwdrmicG
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Thorough review of all 42 source files and 18 test files to create
project context (CLAUDE.md) and agent instructions (AGENTS.md).
CLAUDE.md covers: architecture, namespace map, state machine, key
contracts, conventions, builder patterns, and CI/CD pipeline.
AGENTS.md covers: code review checklist, testing gaps, implementation
patterns, and a prioritized improvement roadmap identifying 16 issues
including unimplemented timeouts, missing retry logic, broken
compensation/saga pattern, and Laravel helper coupling in a
framework-agnostic package.
https://claude.ai/code/session_013CdFJtmtMmSqBZFwdrmicG