.. core-claude documentation master file, created by
   sphinx-quickstart on Fri May  1 11:52:54 2026.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

core-claude
===============================================================================

Claude Code hooks and skills for development, published by ByteCode Solutions.

===============================================================================

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-claude/-/blob/master/LICENSE
    :alt: License

.. image:: https://gitlab.com/bytecode-solutions/core/core-claude/badges/master/pipeline.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-claude/-/pipelines
    :alt: Pipeline Status

.. image:: https://readthedocs.org/projects/core-claude/badge/?version=latest
    :target: https://readthedocs.org/projects/core-claude/
    :alt: Docs Status


Documentation Contents
-------------------------------------------------------------------------------

.. toctree::
   :maxdepth: 2
   :caption: Index:

   quickstart

.. toctree::
   :maxdepth: 2
   :caption: Reference:

   hooks
   skills


What's included
-------------------------------------------------------------------------------

Hooks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* **``.env`` file protection**: a ``PreToolUse`` hook blocks any ``Read``,
  ``Grep``, or ``Bash`` tool call that targets a ``.env`` file at runtime.

* **Declarative deny rules**: a ``.claude/settings.json`` ships with matching
  ``permissions.deny`` rules that enforce the same restrictions before any tool
  is invoked. Every project that installs this plugin must apply these rules
  to its own ``.claude/settings.json``, the hook alone is not sufficient.

* **``/develop`` suggestion**: a ``UserPromptSubmit`` hook detects
  development-related prompts and injects a recommendation to use ``/develop``
  before Claude responds, a nudge, not a forced invocation.

Skills
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* **Create Python project**: scaffold a new Python project from the ByteCode
  Solutions blueprint template via ``/create-python-project [project-name]``.

* **Run linters**: run all linters and type checkers (``ty``, ``ruff``,
  ``mypy``, ``pyright``, ``pylint``) on a Python package sequentially via
  ``/run-linters <package>``. Stops on failure and asks the user whether to
  fix before continuing.

* **Run tests**: run the project test suite via ``/run-tests``. Uses
  ``core-tests`` / ``manager.py`` when available, falls back to pytest.
  Stops on failure, creates one task per failing test, and iterates through
  fixes one by one.

* **Run coverage**: run test coverage via ``/run-coverage``. Uses
  ``core-tests`` / ``manager.py`` when available, falls back to
  ``pytest --cov``. Reports total coverage % and any module below 100 %;
  offers to create one task per under-covered file to reach 100 %. On test
  failure delegates to ``/run-tests``.

* **Run security**: run security checks via ``/run-security <package>``.
  Runs ``bandit`` for static code analysis and ``pip-audit`` for dependency
  CVE scanning, one at a time. Stops on findings and asks the user whether
  to fix before continuing.

* **Develop**: orchestrate a full development task via ``/develop [task description]``.
  Enforces TDD, SOLID, DRY, KISS, YAGNI, and LoD throughout. Enters plan mode,
  reads the codebase, divides the problem, generates Python interface stubs, and
  writes ``PLAN.md`` — stopping to ask the user whenever multiple design approaches
  are viable. Spawns one agent per component (parallel when independent, sequential
  when dependent), each following TDD with 100 % unit coverage and ``/run-linters``.
  After all agents complete, writes integration tests, runs ``/run-linters``,
  ``/run-security``, ``/security-review``, and ``/review``; commits using Conventional
  Commits; generates ``DIAGRAM.md`` if multi-component; and optionally opens a PR.


Installation
-------------------------------------------------------------------------------

.. code-block:: bash

   claude plugin marketplace add https://gitlab.com/bytecode-solutions/core/core-claude.git
   claude plugin install core-claude

To update to the latest version:

.. code-block:: bash

   claude plugin update core-claude@bytecode-solutions

To uninstall:

.. code-block:: bash

   claude plugin uninstall core-claude@bytecode-solutions

After installing, add the declarative deny rules to each project's
``.claude/settings.json``:

.. code-block:: json

   {
     "permissions": {
       "deny": [
         "Read(**/.env*)",
         "Grep(**/.env*)",
         "Bash(cat */.env*)",
         "Bash(cat .env*)"
       ]
     }
   }


Contributing
===============================================================================

Contributions are welcome! Please:

1. Fork the repository.
2. Create a feature branch.
3. Validate the plugin: ``claude plugin validate .``
4. Submit a pull request.


License
===============================================================================

This project is licensed under the MIT License. See the LICENSE file for details.


Links
===============================================================================

* **Documentation:** https://core-claude.readthedocs.io/en/latest/
* **Repository:** https://gitlab.com/bytecode-solutions/core/core-claude
* **Issues:** https://gitlab.com/bytecode-solutions/core/core-claude/-/issues
* **Changelog:** https://gitlab.com/bytecode-solutions/core/core-claude/-/blob/master/CHANGELOG.md


Support
===============================================================================

For questions or support, please open an issue on GitLab or contact the maintainers.


Authors
===============================================================================

* **Alejandro Cora González** - *Initial work* - alek.cora.glez@gmail.com