From 1215585c8c85d3cc8c9ed76d3ad756853402f029 Mon Sep 17 00:00:00 2001 From: henry Date: Sat, 14 Mar 2026 16:42:17 +0800 Subject: [PATCH] =?UTF-8?q?refactor(agent):=20factor=20CLAUDE.md=20from=20?= =?UTF-8?q?213=E2=86=9256=20lines=20with=20prompts=20submodule?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace 213-line CLAUDE.md with a 56-line thin proxy that: - Retains essential commands and helen-specific identity (Hugo static site) - Delegates governance contracts to @third_party/prompts/ @imports - Adds cybermonkey/prompts as third_party/prompts submodule Closes #14 Co-Authored-By: Claude Sonnet 4.6 --- .gitmodules | 3 + CLAUDE.md | 232 +++++++------------------------------------- third_party/prompts | 1 + 3 files changed, 41 insertions(+), 195 deletions(-) create mode 100644 .gitmodules create mode 160000 third_party/prompts diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..3c6a15f --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "third_party/prompts"] + path = third_party/prompts + url = ssh://git@vhost7:9001/cybermonkey/prompts.git diff --git a/CLAUDE.md b/CLAUDE.md index a0eb970..cfc3f9a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,214 +1,56 @@ -# CLAUDE.md +# Helen -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +Company website: Hugo static site for Cybermonkey Ethical Technologies. -## Project Overview +## Commands -This is a Hugo-based static website for Code Monkey Cybersecurity, a cybersecurity company based in Fremantle, Western Australia. The site promotes their "Delphi Notify" XDR/SIEM security service and follows a transparency-focused approach with dual licensing (AGPL v3 and Do No Harm License). - -### Ghost CMS Integration -The project includes a Ghost CMS deployment for managing blog content: -- **Database**: SQLite3 (production-ready, simplified deployment) -- **Port**: 8009 (exposed for Caddy reverse proxy) -- **Mail**: Mailcow SMTP integration -- **Deployment**: Nomad with persistent host volumes -- **No Traefik**: Direct port exposure, TLS handled by Caddy - -## Development Commands - -### Local Development ```bash -# Start development server with drafts enabled -hugo server --buildDrafts - -# Start development server on specific port -hugo server --port 1313 - -# Build for production -hugo --minify +hugo server --buildDrafts # Dev server with drafts +hugo server --port 1313 # Dev on specific port +hugo --minify # Production build +docker-compose up -d # Docker deployment (port 8009) ``` -### Docker Deployment -```bash -# Build and serve via Docker (accessible on port 8009) -docker-compose up -d - -# Stop Docker deployment -docker-compose down -``` +## Governing contracts -### Hugo Installation -```bash -# Install Hugo Extended (Linux) -./install-hugo.sh +**IMPORTANT:** Read the relevant contract before starting any work. -# Manual installation (requires Hugo Extended 0.128.0+) -# Download from https://github.com/gohugoio/hugo/releases/latest -``` +Compact ruleset (60 rules, always loaded): @third_party/prompts/GOVERNANCE-SUMMARY.md -### Ghost CMS Deployment -```bash -# Deploy Ghost with SQLite (production) -./deploy-ghost-sqlite.sh +All governance contracts vendored from `cybermonkey/prompts` at `third_party/prompts/`: -# View logs -nomad alloc logs -f ghost +| Contract | File | Governs | +|----------|------|---------| +| Session workflow | @third_party/prompts/SOAPIER.md | 14-step SOAPIER process | +| Documentation | @third_party/prompts/DOCUMENTATION.md | Diataxis, frontmatter, naming | +| Testing | @third_party/prompts/TESTING.md | 70/20/10, coverage, evidence | +| Git Rules | @third_party/prompts/GIT-RULES.md | Signing, linear history | +| Security | @third_party/prompts/SECURITY.md | Secrets, OWASP, SLSA | -# Backup Ghost data -./nomad/backup-sqlite.sh +## Architecture -# Restore from backup -./nomad/restore-sqlite.sh -``` +- **Hugo Extended 0.128.0+** with SCSS via Hugo Pipes +- **Go-first:** Prefer Hugo's Go-based templating over JS/Node tools +- **Progressive enhancement:** All functionality works without JavaScript +- Content: `content/posts/` (blog), `content/docs/` (pages), `content/docs/training/` (scam education) +- Templates: `layouts/`, Assets: `assets/`, Static: `static/` +- Config: `config.toml`, Base URL: `https://cybermonkey.net.au` -### Docker Troubleshooting -```bash -# Check container status and restart behavior -docker ps -a +## Writing Style -# View container logs for debugging -docker logs +**Target audience:** Home users, small businesses, community groups (not IT professionals) +**Tone:** Approachable, helpful, confidence-building — never intimidating -# Follow container logs in real-time -docker logs -f +**Prohibited:** "Military-grade", "threat intelligence", "killchain", "cyber warfare", padlock symbols, FUD +**Preferred:** "Easy to use", "helps you stay safe", "practical tools", "peace of mind" -# Restart specific service -docker-compose restart +**References:** ~1 citation per 100 words from reputable sources. Work citations naturally into narrative flow. Blog content serves as basis for social media posts. -# Rebuild and restart all services -docker-compose down && docker-compose up -d +## Cross-repo work -# Remove volumes and rebuild (WARNING: destroys data) -docker-compose down -v && docker-compose up -d -``` +If a fix or issue belongs in a different cybermonkey repo: +1. Create the issue in the **target repo** first (`tea issues create --title`) +2. Use the **cross-repo ISoBAR template** from `third_party/prompts/COORDINATION.md` +3. Cross-link issues bidirectionally -### Database Configuration Best Practices -**SQLite Configuration (Ghost CMS)**: -- Always specify full database file path: `database__connection__filename` -- Enable null handling: `database__useNullAsDefault: 'true'` -- Disable debug logging in production: `database__debug: 'false'` -- Use persistent volumes for data directory: `/var/lib/ghost/content` - -**Common Database Connection Issues**: -- Verify database client matches actual database type -- Check that database files/volumes are properly mounted -- Ensure container has write permissions to data directory -- Confirm database service dependencies are met - -## Development Notes -- Always use `hugo server --buildDrafts` for local development to see draft content -- Use `hugo server` for development without draft posts -- Hugo handles all build processes natively without external dependencies - -## Architecture Overview - -### Core Technology Stack -**Hugo Extended 0.128.0+** - Static site generator -**SCSS** - Styling with Hugo's asset pipeline -**Docker + Nginx** - Production deployment - -### Directory Structure -- `content/` - Markdown content files - - `content/posts/` - Blog posts (used to track Facebook/LinkedIn posts and company news) - - `content/docs/` - Main documentation and service pages - - `content/docs/training/` - Scam education and phishing training content - - `content/docs/delphi/` - Delphi Notify product information and sign-up flows - - `content/docs/governance/` - Company policies and compliance documentation - -### Blog Strategy -The `/posts/` section serves dual purposes: -1. **Public blog** for company news, achievements, and industry insights -2. **Social media tracking** - content often repurposed for Facebook/LinkedIn posts -3. **SEO content marketing** Industry-specific articles and case studies - -**Blog content types:** -- Company milestones (Microsoft Founders Sponsorship, Chamber membership, directory listings) -- Security awareness articles and tips -- Case studies and customer success stories -Industry news and commentary -- Product updates and feature announcements -- `layouts/` - Hugo HTML templates and partials -- `assets/` - Source assets (SCSS, JavaScript) -- `static/` - Static files (images, fonts) -- `public/` - Generated site output (excluded from git) - -### Key Configuration -- `config.toml` - Main Hugo configuration -- `go.mod` - Go module dependencies -- `docker-compose.yml` - Container orchestration -- Base URL: `https://cybermonkey.net.au` - - -### Content Features -- Mathematical notation support (KaTeX) -- Diagram rendering (Mermaid) -- Search functionality with JSON index -- Custom Hugo shortcodes for interactive elements -- Multi-theme support (light/dark/auto) - -### Build Process -Hugo handles asset compilation automatically: -- SCSS compilation via Hugo Pipes -- JavaScript minification and bundling -- Search index generation (JSON output format) -- Sitemap and RSS feed generation - -### Development Notes -- Always use `hugo server --buildDrafts` for local development to see draft content -- The site generates JSON search index accessible at `/index.json` -- Custom shortcodes are available in `layouts/shortcodes/` -- Static assets should be placed in `static/` directory -- All content uses Markdown with Hugo frontmatter - -## Writing Style Guidelines - -### Tone and Language -**Target audience**: Home users, small businesses, and community groups (not IT professionals) -**Tone**: Approachable, helpful, and confidence-building rather than intimidating -**Avoid**: Military terminology, threat-focused language, imposing costs, "cyber warfare" rhetoric -**No padlock emojis or symbols** - use friendly alternatives like , , , -**Focus on empowerment** rather than fear-based messaging - -### Prohibited Terms/Phrases -"Military-grade" or "" (use "reliable" or "professional-quality") -"Threat intelligence" or "killchain" -"Cyber warfare" or aggressive security terminology -Padlock symbols (use alternatives) -Fear-inducing language about costs or consequences -FUD - -### Preferred Language -"Easy to use" instead of "-ready" -"Helps you stay safe" instead of "defends against threats" -"Practical tools" instead of "security arsenal" -"Peace of mind" instead of "threat mitigation" -Focus on positive outcomes and user empowerment - -### Reference Guidelines -**Blog posts require citations**: Include approximately one reference/link per 100 words -**Use reputable sources**: Link to research studies, industry reports, government data, established news outlets -**Reference integration**: Work citations naturally into the narrative flow -**Social media ready**: Blog content serves as basis for Facebook, LinkedIn, and Instagram posts - -## Technical Implementation Philosophy - -### Go-First Development Approach -**Primary technology preference**: Go language for all backend functionality -**Hugo integration**: Leverage Hugo's Go-based templating and processing capabilities -**Minimal external dependencies**: Avoid JavaScript, Python, Node.js when Go alternatives exist -**Build process**: Prefer Go-based tools and Hugo's native asset pipeline over complex build systems - -### Language Priority Order -1. **Go** - Primary choice for all server-side logic, data processing, and Hugo templates -2. **Hugo templates** - Go-based templating for all HTML generation -3. **SCSS/CSS** - Styling only, compiled via Hugo Pipes -4. **HTML** - Semantic markup following accessibility standards -5. **JavaScript** - Only when absolutely necessary for client-side interactivity -6. **Other languages** - Avoid unless no Go-based alternative exists - -### Development Constraints -**No unnecessary JavaScript**: Implement features using CSS-only solutions when possible -**Hugo-native functionality**: Use Hugo's built-in features before external tools -**Progressive enhancement**: Ensure all functionality works without JavaScript -**Go tooling**: Prefer Go-based development tools and utilities -**Simple deployment**: Maintain Hugo's static site generation advantages \ No newline at end of file +Repo inventory: moni (backend, vhost11), hecate (gateway, vhost7), contracts (data contracts), aphrodite (UI), prompts (governance) diff --git a/third_party/prompts b/third_party/prompts new file mode 160000 index 0000000..76d26de --- /dev/null +++ b/third_party/prompts @@ -0,0 +1 @@ +Subproject commit 76d26de2f38f19d48e8a9d3722eccdde2c06524d