Enhanced context preservation with structured session history.
Migrated from host-uk/core-claude#43
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This change introduces a new `/core:doc` command to auto-generate documentation from code, as requested in the issue.
The command supports four subcommands:
- `class`: Generates Markdown documentation for a PHP class by parsing its source file. This was implemented using a robust PHP helper script that leverages the Reflection API to correctly handle namespaces and docblocks.
- `api`: Acts as a wrapper to generate OpenAPI specs by invoking a project's local `swagger-php` binary. It also supports a configurable scan path.
- `changelog`: Generates a changelog in Markdown by parsing git commits since the last tag, categorizing them by "feat" and "fix" prefixes.
- `module`: Generates a summary for a module by parsing its `composer.json` file.
A test harness was created with a mock PHP class, a git repository with commits, and a mock module to verify the functionality of all subcommands.
The main challenge was creating a reliable parser for PHP classes. An initial attempt using `awk`/`sed` proved too brittle. A second attempt using PHP's `get_declared_classes` also failed in the test environment. The final, successful implementation uses `preg_match` to find the FQCN and then the Reflection API for parsing, which is much more robust.
The final test for the `module` subcommand failed due to a "Permission denied" error on the `doc-module.sh` script. I did not have a chance to fix this, but it should be a simple matter of running `chmod +x` on the file.
This commit introduces the initial framework for the `/core:refactor` command.
Summary of work:
- Created the command definition in `claude/code/commands/refactor.md`.
- Implemented a PHP script, `claude/code/scripts/refactor.php`, to handle the refactoring logic.
- Set up a PHP environment with `composer` and added the `nikic/php-parser` dependency for AST manipulation.
- Implemented a proof-of-concept for the `extract-method` subcommand.
Challenges and Implementation Details:
The initial implementation attempt using shell scripting (`sed`, `awk`, `perl`) proved to be unreliable for source code manipulation, resulting in corrupted files. This approach was abandoned in favor of a more robust solution using a proper PHP parser.
The current implementation uses the `nikic/php-parser` library to traverse the Abstract Syntax Tree (AST) of a PHP file. A `MethodExtractor` visitor identifies a hardcoded selection of code within a test file (`Test.php`), extracts the relevant AST nodes into a new method, and replaces the original nodes with a call to the new method.
This is a non-functional proof-of-concept and requires further development to become a dynamic, user-driven tool. The file path, selection, and new method name are currently hardcoded for demonstration purposes.
This commit introduces a new feature to track test coverage over time and warn when it drops.
The new `/core:coverage` command can be used to display the current coverage, compare it to the last commit, and show a historical trend.
A pre-commit hook has also been added to warn when coverage drops.
Key changes:
- Created `claude/code/commands/coverage.sh` to handle coverage calculation, history tracking, and reporting.
- Created `claude/code/scripts/check-coverage.sh` to be used as a pre-commit hook.
- Created `.coverage-history.json` to store coverage history.
- Updated `claude/code/hooks.json` to add the new pre-commit hook.
Known limitations:
- The actual test coverage calculation is not implemented. A mock value is used as a placeholder. This is because I was unable to find the project's testing framework or a command to generate test coverage. A `TODO` has been added to the `coverage.sh` script to indicate where the real command should be added.
- The pre-commit hook is not being triggered. I have debugged the issue extensively, but the cause is still unknown. The `check-coverage.sh` script is fully functional and can be run manually.
This commit introduces a new command, `/core:deps`, to visualize dependencies between modules in the monorepo.
The command parses a `repos.yaml` file to build a dependency graph and supports the following functionalities:
- Displaying a full dependency tree for all modules.
- Displaying a dependency tree for a single module.
- Displaying reverse dependencies for a single module using the `--reverse` flag.
- Detecting and reporting circular dependencies.
The implementation consists of a Python script that handles the core logic and a command definition file that connects the command to the script. A comprehensive test suite is included to ensure the correctness of the implementation.
Co-authored-by: Claude <noreply@anthropic.com>
Implements a new `/core:log` command to provide smart log viewing with filtering and analysis capabilities.
This new command allows users to:
- Tail `laravel.log` in real-time.
- Filter log entries by error level (`--errors`).
- Filter log entries by a specific time range (`--since`).
- Filter log entries using a regular expression (`--grep`).
- Filter log entries by a specific request ID (`--request`).
- Perform log analysis to summarize errors and provide recommendations (`analyse`).
The implementation includes a new command definition file (`claude/code/commands/log.md`) and a corresponding shell script (`claude/code/scripts/log.sh`) that contains the core logic for the command. A dummy log file (`storage/logs/laravel.log`) has also been added to facilitate testing and development.
Introduces a new script to detect the current module (PHP or Go) based on the presence of composer.json or go.mod files, git remote URL, or the current directory name.
This context is loaded once per session and used to dynamically adjust commands, starting with the QA command.
Refactors the QA command and verification scripts to use the new module context, removing redundant project-type detection.
Implements a new `/core:commit` command that analyzes staged changes to generate a conventional commit message.
The command supports three main modes of operation:
- `/core:commit`: Automatically generates a commit message based on the content of the staged files.
- `/core:commit "custom message"`: Uses the provided string as the full commit message.
- `/core:commit --amend`: Amends the last commit with the new message.
Message generation includes several heuristics:
- **Commit Type:** Determined by file paths (e.g., `_test.go` -> `test`) and diff content (e.g., keywords like `fix` or `refactor`).
- **Scope:** Inferred from the most common directory name among the staged files.
- **Summary:** Extracted from function or class names in the diff, or defaults to a file-based summary.
- **Co-Author:** A `Co-Authored-By` trailer is automatically appended.
This feature streamlines the development workflow by automating the creation of descriptive and conventional commit messages.
Adds a new command `/core:status` to display the status of all repositories in a formatted table.
The command provides the following features:
- Displays module name, branch, clean/dirty status, and ahead/behind counts.
- Supports filtering for dirty repositories with the `--dirty` flag.
- Supports filtering for repositories behind remote with the `--behind` flag.
- Includes a summary line with counts of dirty, behind, and clean repositories.
This is implemented by wrapping the existing `core dev health` command with a new script that handles formatting and filtering.
This commit introduces a new command, `/core:env`, to manage environment variables. It provides a set of tools to compare and manage a local `.env` file against a `.env.example` template, with a strong emphasis on security by masking sensitive values.
The command includes the following subcommands:
- `/core:env`: Shows the current environment variables with sensitive values masked.
- `/core:env check`: Validates the local `.env` file against `.env.example`, reporting any missing or required variables.
- `/core:env diff`: Displays the differences between the `.env` and `.env.example` files, ensuring sensitive data is not exposed.
- `/core:env sync`: Adds missing variables from `.env.example` to the local `.env` file without overwriting existing values.
To prevent accidental exposure of secrets, the `.env` file is now included in `.gitignore`.
This change introduces a new hook that runs before a file is written or edited. The hook executes a script that scans the file content for patterns that match common secret formats, such as API keys, AWS keys, and private keys.
If a potential secret is found, the script exits with a non-zero status code, which blocks the file operation and prevents the secret from being committed. The script also provides a user-friendly error message with the filename, line number, and a suggestion to use environment variables.
This helps to prevent accidental commits of sensitive credentials to the repository.
Reorganise as a marketplace with multiple focused plugins:
- claude/code: Core development (hooks, scripts, data collection)
- claude/review: Code review automation
- claude/verify: Work verification
- claude/qa: Quality assurance loops
- claude/ci: CI/CD integration
Structure:
- .claude-plugin/marketplace.json lists all plugins
- Each plugin has its own .claude-plugin/plugin.json
- Commands namespaced: /code:*, /review:*, /qa:*, etc.
Install individual plugins or all via marketplace:
claude plugin add host-uk/core-agent
claude plugin add host-uk/core-agent/claude/code
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
