Zenon-Red Repository Setup

Create new repositories using the standard zenon-red template, then customize for your specific project.

Template-Based Approach

All zenon-red repositories should be created from the zenon-red/nexus-template GitHub template:

gh repo create zenon-red/REPO_NAME --template zenon-red/nexus-template --public

Then clone and customize:

gh repo clone zenon-red/REPO_NAME
cd REPO_NAME

Post-Template Customization

After creating from template, follow these steps to customize:

1. Replace Placeholders

Update all REPO_NAME placeholders with your actual repository name:

2. Update Logo

The template includes a placeholder logo .github/nexus-template.png. Replace it:

1. Temporary: Rename nexus-template.png to zr-newborn.png as a placeholder
2. Final: Create your actual 128px PNG logo and save as .github/{repo-name}.png
3. Update README.md to reference the correct logo file

# Rename placeholder first
git mv .github/nexus-template.png .github/zr-newborn.png
# Update README.md to point to zr-newborn.png temporarily
# Later, replace with actual logo:
git mv .github/zr-newborn.png .github/{repo-name}.png

3. Configure Tech Stack

Fill in the TODOs for your technology stack:

4. Update CODEOWNERS (if needed)

Default is @zenon-red/zoe. Change if different ownership is required:

# .github/CODEOWNERS
* @zenon-red/team-name

5. Update Documentation

Remove template-specific files:

• docs/setup.md - This is only for setting up from the template, remove after customization

Create user-facing docs in docs/:

• getting-started.md - Installation and first steps
• commands.md - CLI commands or API reference
• architecture.md - Technical architecture overview
• examples.md - Usage examples

Update docs/README.md index to:

1. Remove the link to setup.md
2. Add links to your new project-specific docs

6. Write Repo-Specific Skill

Replace the placeholder skills/{repo-name}/SKILL.md with actual guidance:

• Tech stack details
• Project architecture
• Development commands (build, test, lint)
• Agent-specific guidelines and pitfalls

7. Install Dependencies & Setup Hooks

# Install your package manager dependencies
npm install  # or cargo, pip, go mod, etc.

# Initialize husky (if using Node.js)
npx husky init

8. First Commit

git add .
git commit -m "chore: initial setup from nexus-template"
git push -u origin main

9. Apply Branch Protection

After first push to main, apply branch protection via the API (free tier — does not require paid GitHub Team plan):

gh api repos/zenon-red/REPO_NAME/branches/main/protection \
  -X PUT \
  -f "enforce_admins=false" \
  -f "required_pull_request_reviews[required_approving_review_count]=0" \
  -f "required_pull_request_reviews[dismiss_stale_reviews]=true" \
  -f "required_pull_request_reviews[require_code_owner_reviews]=true" \
  -f "restrictions=null" \
  -f "allow_force_pushes=false" \
  -f "allow_deletions=false"

This sets:

• No force pushes to main
• No branch deletions
• PR required before merge
• CODEOWNERS review required (from .github/CODEOWNERS)
• Stale reviews dismissed on new pushes
• Admins can bypass (org owner override via enforce_admins=false)

Note: This uses the branch protection endpoint available on all GitHub plans. Do NOT use rulesets (/repos/.../rulesets) — that requires a paid GitHub Team plan.

Target Structure (After Template + Customization)

repo/
├── .github/
│   ├── {repo}.png              # Logo (128px) - replace zr-newborn.png placeholder
│   ├── CODEOWNERS             # Code owners (@zenon-red/zoe default)
│   ├── dependabot.yml         # Dependency updates (configure for your stack)
│   ├── labeler.yml            # PR label patterns
│   ├── settings.yml           # Repo settings and labels
│   └── workflows/
│       ├── ci.yml             # Stack-specific CI pipeline
│       ├── labeler.yml        # Auto-label PRs
│       └── stale-issues-prs.yml
├── .husky/
│   ├── commit-msg             # Commit message validation (optional)
│   ├── pre-commit             # Pre-commit checks (lint, format)
│   └── pre-push               # Pre-push checks (test, build)
├── docs/                      # Documentation
│   ├── README.md              # Docs index (remove setup.md link)
│   ├── getting-started.md     # (create as needed)
│   └── ...                    # Other user docs (setup.md removed)
├── skills/
│   └── {repo-name}/
│       └── SKILL.md           # Repo-specific agent guidance
├── src/                       # Source code (create for your stack)
├── .gitignore                 # Stack-specific ignore patterns
├── CONTRIBUTING.md            # Contribution guidelines (can override org)
├── LICENSE                    # MIT license
├── README.md                  # Main project README
└── {config files}             # package.json, Cargo.toml, etc.

Stack-Specific Hook Examples

pre-commit

# TypeScript/JavaScript
npm run lint:staged && npm run typecheck

# Rust
cargo fmt --check && cargo clippy

# Python
ruff check . && mypy .

# Go
go fmt ./... && go vet ./...

# Deno
deno lint && deno check

pre-push

# TypeScript/JavaScript
npm run check:push

# Rust
cargo test && cargo clippy -- -D warnings

# Python
pytest && ruff check .

# Go
go test ./... && go build ./...

# Deno
deno test && deno lint

Labels (In Template)

The template includes these labels in .github/settings.yml:

Note: Do not remove the task label - it's used by org-level issue templates.

Org-Level Inherited Files

These files are inherited from zenon-red/.github/ when not present:

Checklist

Before considering setup complete:

• Repository created from zenon-red/nexus-template
• README.md updated with actual project name and description
• .github/settings.yml has correct name/description
• Logo renamed from nexus-template.png → zr-newborn.png (temp) or replaced with actual logo
• README.md logo reference updated
• skills/{repo}/SKILL.md renamed and customized
• .github/dependabot.yml configured for package ecosystem
• .github/workflows/ci.yml configured for tech stack
• .husky/pre-commit has appropriate lint/format commands
• .husky/pre-push has appropriate test/build commands
• .gitignore has stack-specific patterns
• docs/setup.md removed (template-specific)
• docs/getting-started.md or equivalent created
• Dependencies installed and package.json/Cargo.toml/etc. configured
• First commit pushed to main
• Branch protection applied (via API, not rulesets)
• All TODO comments in files addressed or removed

Important Notes

• Never create repos from scratch - always use --template zenon-red/nexus-template
• Always keep the task label - it's required by org issue templates
• Always verify husky hooks are executable: chmod +x .husky/*
• The Probot Settings bot will sync labels and repo settings after first push