-
Notifications
You must be signed in to change notification settings - Fork 0
refactor(agent): factor CLAUDE.md from 213→56 lines with prompts submodule (RFC-001) #15
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
CodeMonkeyCybersecurity
wants to merge
1
commit into
main
Choose a base branch
from
refactor/14-claude-md-factoring
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| [submodule "third_party/prompts"] | ||
| path = third_party/prompts | ||
| url = ssh://git@vhost7:9001/cybermonkey/prompts.git | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <alloc-id> 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 <timestamp> | ||
| ``` | ||
| - **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 <container-name> | ||
| **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 <container-name> | ||
| **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 <service-name> | ||
| **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 | ||
| Repo inventory: moni (backend, vhost11), hecate (gateway, vhost7), contracts (data contracts), aphrodite (UI), prompts (governance) |
Submodule prompts
added at
76d26d
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The new submodule URL points to
ssh://git@vhost7:9001/..., which is only resolvable from environments that can reach that internal host and have SSH auth configured; outside that context,git submodule update --initcannot fetchthird_party/prompts, leaving all@third_party/prompts/...governance references inCLAUDE.mdunresolved for fresh and existing clones. In this checkout,git ls-remote ssh://git@vhost7:9001/cybermonkey/prompts.git HEADfails withCould not resolve hostname vhost7, so this regression is immediately reproducible.Useful? React with 👍 / 👎.