Documentation

Customisation

Genesis is designed to be extended. You can add new stack profiles, agent archetypes, templates, and skills without modifying the core workflow.

Adding a new stack profile

Location: .claude/skills/genesis/references/stack-profiles.md

Each profile needs seven sections:

  1. Project Config: package manager, config files, version pinning
  2. Linting and Formatting: tools, hook commands, configuration
  3. Testing: framework, file conventions, coverage tools
  4. Permissions: Bash permission entries for settings.json
  5. Commit Style: Conventional Commits or plain imperative
  6. Folder Structure: idiomatic directory layout
  7. Error Patterns: language-specific error handling conventions

Example: Elixir

Project config uses mix.exs and .tool-versions for runtime version pinning via asdf. Linting uses mix format (built-in) and Credo. Testing uses ExUnit with files at test/**/*_test.exs.

# Permissions
"Bash(mix:*)", "Bash(elixir:*)", "Bash(iex:*)"

# Folder structure
lib/
  <app_name>/
  <app_name>.ex
test/
config/
priv/

Error handling emphasises tagged tuples: {:ok, result} and {:error, reason}, with pattern matching at call sites and never silently ignoring error tuples.

Adding a new agent to the catalogue

Location: .claude/skills/genesis/references/agent-catalogue.md

Required fields:

  • Name: kebab-case identifier
  • Purpose: one-sentence description
  • Model: sonnet for most; opus for security-critical or complex architectural review
  • Tools: Read, Write, Edit, Grep, Glob, Bash
  • Best for: project types where the agent is most valuable

Example: monitoring-designer

Name: monitoring-designer
Purpose: Design observability strategy: metrics, logging, tracing, and alerting
Model: sonnet
Tools: Read, Write, Edit, Grep, Glob
Best for: Production services, microservices, cloud-native applications

Update the Selection Guidelines section after adding new agents.

Creating new templates

Location: .claude/skills/genesis/templates/

Conventions:

  • File extension: .tmpl (e.g., dockerfile.tmpl)
  • Placeholders are uppercase with underscores: {{PLACEHOLDER}}
  • Comments explaining each section assist the claude-infra-writer agent
  • Templates provide structure, not complete implementations

CLAUDE.md placeholders

PlaceholderDescription
{{PROJECT_NAME}}Project name in kebab-case
{{PROJECT_DESCRIPTION}}One-sentence project description
{{STACK_DESCRIPTION}}Language, framework, key dependencies
{{FOLDER_STRUCTURE}}Indented directory tree
{{STACK_ERROR_PATTERNS}}Stack-specific error handling patterns
{{STACK_CODE_STANDARDS}}Stack-specific code standards
{{STACK_TEST_CONFIG}}Test framework configuration
{{COMMIT_STYLE}}Conventional Commits or plain imperative
{{AGENT_LIST}}List of available agents
{{SKILL_LIST}}List of available skills
{{KEY_COMMANDS}}Common commands for the stack
{{ADDITIONAL_RULES}}Extra project-specific rules

Adding new skills

Location: .claude/skills/<skill-name>/SKILL.md

---
name: skill-name
description: One sentence describing when to invoke this skill.
user-invocable: true
---

# Skill Title

Instructions for Claude when this skill is invoked.

## Steps

1. Step one
2. Step two
3. Step three

Adding a skill to Genesis (for generated projects)

  1. Define it in the Skill Selection Guidelines of CLAUDE.md
  2. Map it to the appropriate project types
  3. The claude-infra-writer agent generates a stack-specific SKILL.md

Adding a skill to Genesis itself

  1. Create .claude/skills/<skill-name>/SKILL.md
  2. Add to the banner in CLAUDE.md (Skills line)
  3. Update the Available Skills table in README.md and docs/index.md

Modifying global rules

Location: CLAUDE.md under the Global Rules section. These rules are included verbatim in every generated project's CLAUDE.md.

You can change error handling philosophy, code standards (nesting levels, function length), testing requirements, documentation mandates, and commit conventions.

Language/locale and output style rules come from personalisation.md, not CLAUDE.md. Changes to global rules affect all future generated projects; existing projects have their own copy.

Overriding the scaffold profile

The scaffold profile (lean, standard, full) normally derives from your Claude plan tier. Override methods:

  • Permanently: Edit environment.md, change the Scaffold profile value under Claude Plan
  • Per-project: During the plan phase, request a different profile

Contributing back upstream

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/your-feature
  3. Make changes following existing format and conventions
  4. Test by generating a project using your addition
  5. Run /validate on the generated project
  6. Open a pull request

See CONTRIBUTING.md for full guidelines. Documentation uses Australian English for upstream contributions. Never use em dashes; use commas, semicolons, colons, or full stops.

auto_awesome