Initialize Repo

What It Creates

Base (all types)

~/Projects/<project-name>/
├── .git/                          # Bare git repo
├── .beads/                        # Beads issue database
└── master/                        # Primary worktree
    ├── .beads/redirect            # Points to bare root's .beads/
    ├── .claude/skills/            # Agent skills (copied from dotfiles)
    ├── .gitignore                 # Standard ignores
    ├── .planning/
    │   └── PLANS.md               # ExecPlan format guide
    ├── AGENTS.md                  # Agent instructions (source of truth)
    ├── CLAUDE.md -> AGENTS.md     # Symlink for Claude Code
    └── README.md                  # Project README

sui-dapp additions

    ├── .envrc                     # Nix flake integration for direnv
    ├── contracts/<project-name>/  # Sui Move package
    │   ├── Move.toml
    │   ├── sources/
    │   └── tests/
    ├── contracts/docs/
    ├── flake.nix                  # Nix dev environment with Sui
    ├── flake.lock
    ├── frontend/
    │   ├── src/
    │   ├── static/
    │   └── docs/
    └── zklogin-backend/           # Optional zkLogin service

python additions

    ├── .envrc
    ├── .python-version
    ├── flake.nix                  # Nix dev environment with Python + uv
    ├── flake.lock
    ├── pyproject.toml             # uv-managed project
    ├── src/<project-name>/
    │   └── __init__.py
    └── tests/
        └── test_placeholder.py

rust additions

    ├── .envrc
    ├── flake.nix                  # Nix dev environment with Rust
    ├── flake.lock
    ├── Cargo.toml
    ├── rust-toolchain.toml
    └── src/
        └── lib.rs

ocaml additions

    ├── .envrc
    ├── .ocamlformat              # OCamlformat config
    ├── flake.nix                  # Nix dev environment with OCaml
    ├── flake.lock
    ├── dune-project               # Dune build system config
    ├── <project-name>.opam        # Generated by dune
    ├── bin/
    │   ├── dune
    │   └── main.ml
    ├── lib/
    │   ├── dune
    │   └── <project-name>.ml
    └── test/
        ├── dune
        └── test_<project-name>.ml

node additions

    ├── .envrc
    ├── flake.nix                  # Nix dev environment with Node.js
    ├── flake.lock
    ├── package.json               # pnpm-managed project
    ├── tsconfig.json              # TypeScript config
    └── src/
        └── index.ts

go additions

    ├── .envrc
    ├── flake.nix                  # Nix dev environment with Go
    ├── flake.lock
    ├── go.mod                     # Go module
    ├── main.go
    └── main_test.go

Instructions

When this skill is invoked, follow the steps in order: Part 1 (base), then Part 2 (type-specific, skip for bare), then Part 3 (finalization).

Part 1: Base Setup (all types)

Step B1: Create bare repo and master worktree

cd ~/Projects
mkdir <project-name>
cd <project-name>
git init --bare .git
git worktree add -b master master
cd master

The git worktree add -b master master command creates an orphan branch since there are no existing refs.

Step B2: Create base directory structure

cd ~/Projects/<project-name>/master
mkdir -p .planning .claude/skills

Step B3: Write .gitignore

Standard ignores for Nix, Node, Python, Rust, IDE, OS, and environment files:

# Nix
result
result-*
.direnv/

# Node
node_modules/
dist/
.next/
.nuxt/

# Python
__pycache__/
*.pyc
*.egg-info/
.venv/
.mypy_cache/
.pytest_cache/
.ruff_cache/

# Rust
target/

# OCaml
_build/
*.install

# Go
/vendor/

# IDE
.idea/
.vscode/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

# Environment
.env
.env.local
.env.*.local

Step B4: Fetch PLANS.md

Fetch the ExecPlan format guide from the OpenAI cookbook:

gh api repos/openai/openai-cookbook/contents/articles/codex_exec_plans.md --jq '.content' | base64 -d

Extract the content inside the ~~~md code fence (starting with # Codex Execution Plans (ExecPlans):) and write it to .planning/PLANS.md. Do not include the article wrapper.

Step B5: Copy skills from dotfiles

Copy the skill directories from ~/Projects/dotfiles/.claude/skills/ into the repo's .claude/skills/:

• stacked-prs/
• ask-agent/
• spawn-agent/
• initialize-repo/ (this skill)

Preserve executable permissions on scripts.

Part 2: Type-Specific Setup

Run the section matching the selected --type. Skip this part entirely for bare.

Type: sui-dapp

Step S1: Create directory structure

cd ~/Projects/<project-name>/master
mkdir -p contracts/docs frontend/src frontend/static frontend/docs

Step S2: Scaffold the Move contract

cd ~/Projects/<project-name>/master/contracts
nix develop --command sui move new <project-name>

This generates Move.toml, sources/<project-name>.move, and tests/<project-name>_tests.move automatically. Do not write these by hand.

Step S3: Create placeholder files

Write empty .gitkeep files in:

• contracts/docs/.gitkeep
• frontend/src/.gitkeep
• frontend/static/.gitkeep
• frontend/docs/.gitkeep

Step S4: Write flake.nix

Write a Nix flake that provides a dev shell with the Sui CLI (pinned binary release), Node.js, pnpm, TypeScript, Rust toolchain, and general utilities. The flake should:

• Use nixpkgs (nixos-unstable) and flake-utils as inputs
• Fetch the Sui binary from GitHub releases using pkgs.fetchurl
• Support x86_64-linux and aarch64-linux with platform-specific hashes
• Use autoPatchelfHook for binary compatibility on NixOS/non-FHS systems
• Include a shell hook that prints tool versions on entry

To get the correct Sui version and hashes:

1. Check the latest Sui release: gh api repos/MystenLabs/sui/releases/latest --jq '.tag_name'
2. Download the tarball for each platform and compute the SRI hash: nix hash to-sri --type sha256 $(nix-prefetch-url --unpack <url>)

Step S5: Write .envrc

Content: use flake

sui-dapp AGENTS.md sections

Include these in the AGENTS.md written during Part 3:

• Contract build/test: nix develop --command sui move build, nix develop --command sui move test (from contracts dir)
• Frontend: pnpm install, pnpm dev, pnpm build, pnpm test
• Directory layout showing contracts/, frontend/, zklogin-backend/

Type: python

Step P1: Create directory structure

cd ~/Projects/<project-name>/master
mkdir -p src/<project-name> tests

Step P2: Write pyproject.toml

[project]
name = "<project-name>"
version = "0.1.0"
description = "<description>"
requires-python = ">=3.12"
dependencies = []

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
]

[tool.ruff]
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "I", "UP"]

[tool.pytest.ini_options]
testpaths = ["tests"]

Step P3: Write initial source files

• src/<project-name>/__init__.py: empty file
• tests/test_placeholder.py:

  def test_placeholder():
      pass
  

Step P4: Write .python-version

Content: 3.12

Step P5: Write flake.nix

Write a Nix flake providing a dev shell with Python 3.12, uv, and ruff:

• Use nixpkgs (nixos-unstable) and flake-utils as inputs
• Support x86_64-linux and aarch64-linux
• Include a shell hook that prints Python and uv versions

Step P6: Write .envrc

Content: use flake

python AGENTS.md sections

Include these in the AGENTS.md written during Part 3:

• Package management: uv sync, uv add <pkg>
• Testing: uv run pytest
• Linting: uv run ruff check ., uv run ruff format .
• Src layout: src/<project-name>/

Type: rust

Step R1: Initialize Cargo project

cd ~/Projects/<project-name>/master
nix develop --command cargo init --lib --name <project-name>

Step R2: Write rust-toolchain.toml

[toolchain]
channel = "stable"
components = ["rustfmt", "clippy"]

Step R3: Write flake.nix

Write a Nix flake providing a dev shell with Rust (stable), cargo, clippy, rustfmt, and rust-analyzer:

• Use nixpkgs (nixos-unstable) and flake-utils as inputs
• Use the nixpkgs Rust toolchain
• Support x86_64-linux and aarch64-linux
• Include a shell hook that prints rustc and cargo versions

Step R4: Write .envrc

Content: use flake

rust AGENTS.md sections

Include these in the AGENTS.md written during Part 3:

• Build: cargo build
• Test: cargo test
• Lint: cargo clippy -- -D warnings
• Format: cargo fmt

Type: ocaml

Step O1: Create directory structure

cd ~/Projects/<project-name>/master
mkdir -p bin lib test

Step O2: Write dune-project

(lang dune 3.0)
(name <project-name>)
(generate_opam_files true)

(package
 (name <project-name>)
 (synopsis "<description>")
 (depends
  (ocaml (>= 5.1))
  (dune (>= 3.0))
  (alcotest (and :with-test (>= 1.7)))))

Step O3: Write dune build files

• lib/dune:

  (library
   (name <project-name>)
   (public_name <project-name>))
  

• lib/<project-name>.ml:

  let greeting () = "Hello from <project-name>"
  

• bin/dune:

  (executable
   (name main)
   (public_name <project-name>)
   (libraries <project-name>))
  

• bin/main.ml:

  let () = print_endline (<Project_name>.greeting ())
  

• test/dune:

  (test
   (name test_<project-name>)
   (libraries <project-name> alcotest))
  

• test/test_<project-name>.ml:

  let test_greeting () =
    Alcotest.(check string) "greeting" "Hello from <project-name>"
      (<Project_name>.greeting ())
  
  let () =
    Alcotest.run "<project-name>"
      [ ("basic", [ Alcotest.test_case "greeting" `Quick test_greeting ]) ]
  

Note: <Project_name> uses OCaml module naming (capitalize first letter, underscores preserved).

Step O4: Write .ocamlformat

profile = default

Step O5: Write flake.nix

Write a Nix flake providing a dev shell with OCaml 5.1+, dune, opam, ocaml-lsp-server, ocamlformat, and utop:

• Use nixpkgs (nixos-unstable) and flake-utils as inputs
• Use pkgs.ocaml-ng.ocamlPackages_5_1 (or latest 5.x available)
• Include alcotest for tests
• Support x86_64-linux and aarch64-linux
• Include a shell hook that prints OCaml and dune versions

Step O6: Write .envrc

Content: use flake

ocaml AGENTS.md sections

Include these in the AGENTS.md written during Part 3:

• Build: dune build
• Test: dune test
• Run: dune exec <project-name>
• Format: dune fmt
• Clean: dune clean
• REPL: dune utop lib

Type: node

Step N1: Create directory structure

cd ~/Projects/<project-name>/master
mkdir -p src

Step N2: Write package.json

{
  "name": "<project-name>",
  "version": "0.1.0",
  "description": "<description>",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "test": "node --test dist/**/*.test.js",
    "lint": "tsc --noEmit"
  },
  "devDependencies": {
    "typescript": "^5.5"
  }
}

Step N3: Write tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["src"]
}

Step N4: Write initial source file

• src/index.ts:

  export function hello(): string {
    return "Hello from <project-name>";
  }
  

Step N5: Write flake.nix

Write a Nix flake providing a dev shell with Node.js (LTS) and pnpm:

• Use nixpkgs (nixos-unstable) and flake-utils as inputs
• Support x86_64-linux and aarch64-linux
• Include a shell hook that prints Node and pnpm versions

Step N6: Write .envrc

Content: use flake

Step N7: Install dependencies

cd ~/Projects/<project-name>/master
nix develop --command pnpm install

This generates pnpm-lock.yaml.

node AGENTS.md sections

Include these in the AGENTS.md written during Part 3:

• Install: pnpm install
• Build: pnpm build
• Dev: pnpm dev
• Test: pnpm test
• Lint: pnpm lint

Type: go

Step G1: Initialize Go module

cd ~/Projects/<project-name>/master
nix develop --command go mod init github.com/tedks/<project-name>

Step G2: Write main.go

package main

import "fmt"

func Greeting() string {
	return "Hello from <project-name>"
}

func main() {
	fmt.Println(Greeting())
}

Step G3: Write main_test.go

package main

import "testing"

func TestGreeting(t *testing.T) {
	got := Greeting()
	want := "Hello from <project-name>"
	if got != want {
		t.Errorf("Greeting() = %q, want %q", got, want)
	}
}

Step G4: Write flake.nix

Write a Nix flake providing a dev shell with Go, gopls, and golangci-lint:

• Use nixpkgs (nixos-unstable) and flake-utils as inputs
• Support x86_64-linux and aarch64-linux
• Include a shell hook that prints Go version

Step G5: Write .envrc

Content: use flake

go AGENTS.md sections

Include these in the AGENTS.md written during Part 3:

• Build: go build ./...
• Test: go test ./...
• Lint: golangci-lint run
• Run: go run .

Part 3: Finalization (all types)

Step F1: Write AGENTS.md

Write agent instructions covering:

• Project overview and description
• Project structure (directory layout — adapt to the selected type)
• Environment setup (Nix + direnv if the type includes a flake, or just note "no special environment" for bare)
• ExecPlans reference to .planning/PLANS.md
• Beads issue tracking quick reference (bd ready, bd show, bd create, etc.)
• Beads worktree setup (the portable redirect recipe using git worktree list --porcelain)
• Type-specific build and test commands (see the "AGENTS.md sections" in the type above)
• Git workflow: PR-only, draft PRs early, normal merges, stacked PRs, granular commits, worktrees

Step F2: Create CLAUDE.md symlink

cd ~/Projects/<project-name>/master
ln -s AGENTS.md CLAUDE.md

Step F3: Write README.md

A user-facing README with:

• Project title and description
• Prerequisites (Nix if applicable, or just git for bare)
• Getting started (type-specific: build/test/run commands)
• Project structure overview
• Link to AGENTS.md for contributing

Step F4: Generate flake.lock (types with a flake only)

cd ~/Projects/<project-name>/master
nix develop --command echo "flake loaded"

This generates flake.lock and validates the flake works. Skip this step for bare.

Step F5: Initial commit

cd ~/Projects/<project-name>/master
git add -A
git commit -m "Initial project scaffold: <project-name>

<type-specific summary of what was set up>"

Step F6: Create GitHub repo and push

gh repo create tedks/<project-name> --private --description "<description>"
cd ~/Projects/<project-name>/master
git remote add origin [email protected]:tedks/<project-name>.git
git push -u origin master

Note: gh repo create --source does not work from a worktree. Create the repo without --source, then add the remote manually.

Step F7: Initialize beads

Beads must be initialized from the bare repo root, not from a worktree:

cd ~/Projects/<project-name>
bd init --branch beads-metadata --prefix <project-name>

Then configure it:

1. Edit .beads/config.yaml: set no-daemon: true
2. Delete the stray AGENTS.md that bd init creates at the bare root: rm ~/Projects/<project-name>/AGENTS.md
3. Create the redirect in the worktree:

   cd ~/Projects/<project-name>/master
   mkdir -p .beads
   printf '%s\n' ../.beads > .beads/redirect
   

4. Commit and push the redirect:

   git add .beads/redirect
   git commit -m "Add beads issue tracking redirect for worktree"
   git push
   

Step F8: Set up branch protection

Create a GitHub ruleset requiring PRs for the master branch:

cd ~/Projects/<project-name>/master
gh api repos/tedks/<project-name>/rulesets -X POST --input - <<'RULES'
{
  "name": "protect-master",
  "target": "branch",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "include": ["refs/heads/master"],
      "exclude": []
    }
  },
  "rules": [
    {
      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 0,
        "dismiss_stale_reviews_on_push": false,
        "require_code_owner_review": false,
        "require_last_push_approval": false,
        "required_review_thread_resolution": false
      }
    }
  ]
}
RULES

Step F9: Verify

Run the following checks:

• cd ~/Projects/<project-name>/master && git status — clean working tree
• git worktree list — shows bare root and master worktree
• bd ready — beads works (returns empty list)

Type-specific checks (skip for bare):

• nix develop --command echo "ok" — Nix shell loads
• sui-dapp: nix develop --command sui --version, nix develop --command sui move build (from contracts dir)
• python: nix develop --command python --version, nix develop --command uv run pytest
• rust: nix develop --command cargo --version, nix develop --command cargo test
• ocaml: nix develop --command ocaml --version, nix develop --command dune build, nix develop --command dune test
• node: nix develop --command node --version, nix develop --command pnpm build, nix develop --command pnpm test
• go: nix develop --command go version, nix develop --command go test ./...

Report the results to the user.

Notes

• The Sui binary version and hashes will need updating as new releases come out. Check gh api repos/MystenLabs/sui/releases/latest for the current version.
• The skill assumes the user's GitHub username is tedks. Adjust the gh repo create and remote URL if needed.
• Skills are copied into the repo (not symlinked) so the repo is self-contained. Check ~/Projects/dotfiles/.claude/skills/ for upstream updates periodically.
• To add a new project type: add a new section under Part 2, define its AGENTS.md sections, and add verification checks to Step F9.