# ursisterbtw/ccprompts architecture

> Architecture diagram of the GitHub repository ursisterbtw/ccprompts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ursisterbtw/ccprompts
- Repository: https://github.com/ursisterbtw/ccprompts

## Overview

##### Project Type and Purpose
- This is a CLI-centric command/agent framework (“ccprompts”) for Claude Code, providing ~70 reusable commands across development phases, plus agent templates, safety-wrapped execution, validation, workflows, and CI/CD integration.
- It’s not a monolithic web app but a “toolchain” library: commands live under `.claude/`, agents under `agents/`, execution tooling in `scripts/` and `src/` (Dagger safety container), plus docs, tests, and GitHub workflows.

a. CLI Interface
- src/index.ts – entry point
- package.json scripts (`npm run validate`, `npm run test`, etc.)
b. Command Registry
- `.claude/commands/*/*.md` – individual command definitions organized by phase
- `.claude/settings.json` and config.json – ecosystem configuration
- templates/SUB_AGENT_TEMPLATE.md – skeleton for sub-agent generation
c. Agent System
- `.claude/agents/*.md` – built-in agent specs
- Workflow orchestrator (YAML under `.claude/workflows/`) to chain commands
d. Safety & Validation Engine
- scripts/ – shell wrappers (safe-run.sh/quick-safe.sh), JS validators (validators/*.js), safety-patterns.js
- src/ – Dagger container definitions for sandboxed command execution
e. Testing Suite
- tests/ – Jest tests for command structure, integration, safety, performance, validators
- jest.config.js, setup/teardown scripts
f. Documentation & Examples
- docs/ – API reference, developer guide, usage, workflow guides, safety documentation, assets
g. CI/CD & Automation
- .github/workflows/ – primary pipelines (validate prompts, code review, security scan)
- .github/actions/ – reusable actions (setup-node, security-scan, artifact-handling)
h. External Services
- GitHub Actions – for CI, tests, linting, markdown-link-check
- Dagger.io – container runtime for safe execution

- User CLI → (invokes) → src/index.ts → (loads) → Command Registry
- Command Registry → (feeds) → Safety & Validation Engine → (spawns) → Dagger Container
- Dagger Container → (executes) → Host filesystem changes or external tools → returns results
- Agent System → (provides templates) → Command Registry & Workflows → orchestrated by index.ts
- Tests Suite → (validates) → Command definitions, Validation Engine, Agent configs
- CI/CD Pipelines → (trigger) → Tests Suite & Validation Engine → (report) → GitHub UI

##### Architectural Patterns & Design Principles
- Plugin architecture: commands are “plugins” described in Markdown, loaded at runtime.
- Sandbox pattern: Dagger containers isolate risky operations.
- Convention over configuration: phases (00–11) define structure.
- Template method: agent-template-wizard uses a 7-step methodology to scaffold new agents.
- Declarative workflows: YAML files in `.claude/workflows/` define multi-step processes.

##### Technologies & Frameworks
- Node.js & TypeScript (src/index.ts, npm scripts)
- Dagger.io for containerized safety
- Jest for testing
- GitHub Actions for CI/CD
- YAML for workflows
- Shell scripts for quick wrapper utilities
- Markdown for command/agent definitions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors and User-Facing
    User["User"]:::external
    CLI["CLI Interface"]:::frontend
    User -->|"invokes"| CLI

    %% Command Registry Layer
    subgraph "Command Registry" 
        direction TB
        CMD_FILES[".claude/commands/"]:::frontend
        SETTINGS[".claude/settings.json"]:::frontend
        TEMPLATE["templates/SUB_AGENT_TEMPLATE.md"]:::frontend
    end
    CLI -->|"loads commands"| CMD_FILES
    CLI -->|"loads config"| SETTINGS
    CLI -->|"uses template"| TEMPLATE

    %% Agent System Layer
    subgraph "Agent System" 
        direction TB
        AGENTS[".claude/agents/"]:::frontend
        WORKFLOWS[".claude/workflows/"]:::frontend
    end
    CMD_FILES -->|"feeds"| AGENTS
    AGENTS -->|"provides specs"| CMD_FILES
    AGENTS -->|"defines workflows"| WORKFLOWS
    WORKFLOWS -->|"orchestrated by"| CLI

    %% Safety & Validation Engine
    subgraph "Safety & Validation Engine"
        direction TB
        SAFE_RUN["scripts/safe-run.sh"]:::core
        QUICK_SAFE["scripts/quick-safe.sh"]:::core
        PATTERNS["scripts/config/safety-patterns.js"]:::core
        VAL_JS["scripts/safety-validator.js"]:::core
        VAL_CMD["scripts/validate-commands.js"]:::core
        VALIDATORS["scripts/validators/"]:::core
        DAGGER_CFG["dagger.json"]:::core
    end
    CMD_FILES -->|"feeds"| SAFE_RUN
    SETTINGS --> SAFE_RUN
    SAFE_RUN -->|"calls"| VAL_JS
    VAL_CMD -->|"validates commands"| CMD_FILES
    SAFE_RUN -->|"uses patterns"| PATTERNS
    SAFE_RUN -->|"spawns"| DAGGER
    VAL_JS --> VALIDATORS

    %% Dagger Container
    subgraph "Dagger Sandbox"
        direction TB
        DAGGER["Dagger Container"]:::core
    end
    SAFE_RUN -->|"spawns"| DAGGER
    DAGGER -->|"executes in sandbox"| HostFS
    DAGGER -->|"returns results"| CLI

    HostFS["Host Filesystem / Console"]:::infra

    %% Testing Suite
    subgraph "Testing Suite"
        direction TB
        TESTS["tests/"]:::infra
        JEST_CFG["jest.config.js"]:::infra
    end
    TESTS -->|"validates"| CMD_FILES
    TESTS -->|"tests engine"| SAFE_RUN
    TESTS -->|"tests agents"| AGENTS

    %% CI/CD & Automation
    subgraph "CI/CD Pipelines"
        direction TB
        GH_WF[".github/workflows/"]:::infra
        GH_ACT[".github/actions/"]:::infra
        WF_CFG[".github/workflow-config.yml"]:::infra
    end
    GH_WF -->|"triggers"| TESTS
    GH_WF -->|"runs"| SAFE_RUN
    GH_WF -->|"reports to"| GitHubUI

    %% External Services
    subgraph "External Services"
        direction TB
        GitHubUI["GitHub Actions"]:::external
        DaggerIO["Dagger.io"]:::external
    end
    GH_WF --> GitHubUI
    DAGGER --> DaggerIO

    %% Click Events
    click CLI "https://github.com/ursisterbtw/ccprompts/blob/main/src/index.ts"
    click CMD_FILES "https://github.com/ursisterbtw/ccprompts/tree/main/.claude/commands/"
    click SETTINGS "https://github.com/ursisterbtw/ccprompts/blob/main/.claude/settings.json"
    click TEMPLATE "https://github.com/ursisterbtw/ccprompts/blob/main/templates/SUB_AGENT_TEMPLATE.md"
    click AGENTS "https://github.com/ursisterbtw/ccprompts/tree/main/.claude/agents/"
    click WORKFLOWS "https://github.com/ursisterbtw/ccprompts/tree/main/.claude/workflows/"
    click SAFE_RUN "https://github.com/ursisterbtw/ccprompts/blob/main/scripts/safe-run.sh"
    click QUICK_SAFE "https://github.com/ursisterbtw/ccprompts/blob/main/scripts/quick-safe.sh"
    click PATTERNS "https://github.com/ursisterbtw/ccprompts/blob/main/scripts/config/safety-patterns.js"
    click VAL_JS "https://github.com/ursisterbtw/ccprompts/blob/main/scripts/safety-validator.js"
    click VAL_CMD "https://github.com/ursisterbtw/ccprompts/blob/main/scripts/validate-commands.js"
    click VALIDATORS "https://github.com/ursisterbtw/ccprompts/tree/main/scripts/validators/"
    click DAGGER_CFG "https://github.com/ursisterbtw/ccprompts/blob/main/dagger.json"
    click TESTS "https://github.com/ursisterbtw/ccprompts/tree/main/tests/"
    click JEST_CFG "https://github.com/ursisterbtw/ccprompts/blob/main/jest.config.js"
    click GH_WF "https://github.com/ursisterbtw/ccprompts/tree/main/.github/workflows/"
    click GH_ACT "https://github.com/ursisterbtw/ccprompts/tree/main/.github/actions/"
    click WF_CFG "https://github.com/ursisterbtw/ccprompts/blob/main/.github/workflow-config.yml"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#0366d6,color:#0366d6
    classDef core fill:#DFF7AE,stroke:#6aa84f,color:#38761d
    classDef infra fill:#E0E0E0,stroke:#999999,color:#333333
    classDef external fill:#F7DAAE,stroke:#e69138,color:#953735
```
