Skip to content

README.md

Latest commit

 

History

History
265 lines (195 loc) · 11.5 KB

README.md

File metadata and controls

265 lines (195 loc) · 11.5 KB

Cracking Shells Playbook

License

The comprehensive instruction set for LLM coding agents working within the Cracking Shells organization.

This playbook provides standardized guidelines, workflows, and best practices that ensure consistency, quality, and efficiency across all repositories in the organization. It serves as the authoritative reference for AI coding agents to understand organizational standards and deliver high-quality contributions.

Table of Contents

Installation

Skills are packaged as .skill files — zip archives that Claude Code extracts into its skills directory. Each release publishes one .skill file per skill as a GitHub Release asset.

Option A — Download from GitHub Releases (recommended)

  1. Go to the Releases page and download <skill-name>.skill for the skill you want.

  2. Install it into Claude Code:

    User-level install (skill available in every project):

    mkdir -p ~/.claude/skills
unzip <skill-name>.skill -d ~/.claude/skills/

    Project-level install (skill available only in the current repo):

    mkdir -p .claude/skills
unzip <skill-name>.skill -d .claude/skills/

  3. Restart Claude Code (or reload the window) for the new skill to appear.

    Claude Desktop: .skill file installation via the Claude Desktop UI is not currently documented for this file format. Use the Claude Code CLI paths above, or check the Claude Desktop settings for any skill management options available in your version.

Option B — Clone and build locally

Use this option if you want to modify a skill before installing, or if you need to build from the latest commit rather than a release.

  1. Clone the repository and install dev dependencies:

    git clone https://github.com/CrackingShells/cracking-shells-playbook.git
cd cracking-shells-playbook
make dev-setup

  2. Package the skill you want:

    uv run tools/package_skill.py skills/<skill-name> dist/

  3. Install the output .skill file using the same unzip steps from Option A:

    unzip dist/<skill-name>.skill -d ~/.claude/skills/

Option C — Build Rust from source (managing-roadmaps only)

The managing-roadmaps skill ships a pre-compiled Rust CLI (dirtree-rdm). Use this option only if no pre-compiled binary matches your platform (e.g., Linux arm64 without a matching release asset).

  1. Install Rust via rustup if not already present.
  2. Build the binary for your local platform: 
    cd skills/managing-roadmaps/scripts/dirtree-rdm
bash build.sh local
    This detects your OS and architecture automatically and writes the binary to bin/.
  3. Copy the binary to the expected name (e.g., dirtree-rdm-darwin-arm64) if the packager does not pick it up automatically.
  4. Return to the repo root and follow Option B to package and install: 
    cd ../../../..
uv run tools/package_skill.py skills/managing-roadmaps dist/
unzip dist/managing-roadmaps.skill -d ~/.claude/skills/

Overview

The Cracking Shells Playbook is a living document system that defines:

  • Development workflows for Git, testing, and code changes
  • Documentation standards for technical writing and visual diagrams
  • Reporting guidelines for analysis, implementation, and knowledge transfer
  • Work ethics promoting thoroughness, persistence, and quality
  • Organizational conventions ensuring consistency across projects

Philosophy

This playbook embodies the organization's commitment to:

  • Quality over speed: Thorough analysis and implementation
  • Documentation-driven development: Clear, comprehensive documentation
  • Test-driven validation: Robust testing at all stages
  • Systematic problem-solving: Root cause analysis over shortcuts
  • Knowledge preservation: Comprehensive reporting and knowledge transfer

Quick Start for LLM Agents

First-Time Setup

  1. Read this README to understand the playbook structure
  2. Review Work Ethics for core principles
  3. Study Git Workflow for commit and branching standards
  4. Understand Reporting Guidelines for documentation requirements

Standard Workflow

graph TD
    A[Receive Task] --> B[Review Relevant Instructions]
    B --> C[Create Analysis Report with Mermaid Diagrams]
    C --> D[Get User Approval]
    D --> E[Implement with Tests]
    E --> F[Create Knowledge Transfer Report]

    style C fill:#fff3e0
    style F fill:#fff3e0
Loading

Essential Instructions by Task Type

Task Type Required Reading
New Feature Code Change Phases, Testing, Reporting
Bug Fix Work Ethics, Testing, Git Workflow
Documentation Documentation, Style Guide, Resources
Refactoring Code Change Phases, Testing
Testing Testing, Reporting

Instruction Categories

The playbook is organized into specialized instruction files covering different aspects of development:

graph TD
    Playbook[Cracking Shells Playbook]
    
    Playbook --> Workflow[Workflow & Process]
    Playbook --> Docs[Documentation]
    Playbook --> Quality[Quality & Testing]
    Playbook --> Ethics[Work Ethics]
    
    Workflow --> Git[Git Workflow]
    Workflow --> Phases[Code Change Phases]
    Workflow --> Reporting[Reporting Guidelines]
    Workflow --> Roadmap[Roadmap Generation]
    
    Docs --> DocMain[Documentation Overview]
    Docs --> Structure[Structure Standards]
    Docs --> Style[Style Guide]
    Docs --> API[API Documentation]
    Docs --> Resources[Resources & Diagrams]
    Docs --> MkDocs[MkDocs Setup]
    Docs --> Tutorials[Tutorial Writing]
    Docs --> README[README Standards]
    
    Quality --> Testing[Testing Guidelines]
    Quality --> Analytic[Analytic Behavior]
    Quality --> Docstrings[Python Docstrings]
    
    Ethics --> WorkEthics[Work Ethics Guidelines]
    
    style Playbook fill:#e1f5ff
    style Workflow fill:#fff4e1
    style Docs fill:#e8f5e9
    style Quality fill:#f3e5f5
    style Ethics fill:#fce4ec
Loading

Instruction File Organization

📋 Workflow & Process

📚 Documentation

✅ Quality & Testing

💪 Work Ethics

How to Use This Playbook

For LLM Coding Agents

1. Identify Relevant Instructions

2. Follow the Standard Workflow

All development follows: Analysis → Test Definition → User Approval → Implementation → Knowledge Transfer

Key Principles:

  • Create reports for analysis, test definitions, and knowledge transfer
  • Iterate on reports with user feedback before implementation
  • Define tests before implementing
  • Use Mermaid diagrams to visualize architecture, workflows, and data flows

3. Maintain Quality Standards

From Work Ethics:

  • Root cause analysis over shortcuts
  • Systematic debugging with evidence-based validation
  • Research-first approach before implementation
  • Commit discipline with clear, focused commits

See Reporting Guidelines and Documentation Resources for detailed standards.

For Human Developers

This playbook serves as an onboarding guide, reference documentation, and quality checklist for understanding organizational standards and working effectively with AI coding agents.

Contributing

Updating Instructions

  1. Identify which instruction files need updates
  2. Ensure changes align with existing standards
  3. Update cross-references in related instruction files
  4. Test against existing repositories
  5. Document rationale for changes

Quality Standards

All playbook updates must:

  • ✅ Follow the organization's own standards (dogfooding)
  • ✅ Include clear examples and use cases
  • ✅ Use Mermaid diagrams where appropriate
  • ✅ Maintain backward compatibility when possible

License

This playbook is licensed under the AGPL-3.0 License - see the LICENSE file for details.

Maintained by: Cracking Shells Organization Last Updated: 2025-11-07 Version: 1.0.0

For questions or suggestions, please open an issue in this repository.