Skip to main content
Development

Project Scaffolding

Project structure — standard files, documentation conventions, and dispatch to language-specific scaffolds. Use when creating or standardizing projects. Delegates to scaffold-rust, scaffold-go, scaffold-python, scaffold-node, or scaffold-terraform for CI/CD, release pipelines, and language-specific config.

scaffold-project View on GitHub →

Project Scaffolding

Development Philosophy

Every project should be understandable by a junior developer. Self-documenting structure. Skills as documentation. Minimal setup friction.

Language-Specific Scaffolds

After generating standard files, load the appropriate language skill for CI/CD, release, and tooling:

LanguageSkillKey Tools
Rustscaffold-rustcargo, clippy, rustfmt, cross, crates.io
Goscaffold-gogo, golangci-lint, gofmt
Pythonscaffold-pythonuv, ruff, pytest, ty
Node/TSscaffold-nodenpm, biome, tsc
Terraformscaffold-terraformterraform, AWS OIDC

Always generate the standard files below first, then apply the language-specific scaffold.

Standard Files (Every Project)

FilePurpose
README.mdHuman-facing documentation (see write-readme)
AGENTS.mdAI-facing project context (see configure-ai)
LICENSEApache-2.0 (standard for all repos)
CONTRIBUTING.mdHow to contribute (see template below)
sr.yamlSemantic release config
.envrcNix shell activation (use flake .#<shell>)
llms.txtLLM-friendly project summary (see create-llms-txt)
skills/<name>/SKILL.mdAgent skill instructions
docs/Project documentation (guides/, rfcs/, plans/, runbooks/, etc.)
.ai-memory/Tool-agnostic AI memory (see memory skill)
.github/workflows/ci.ymlQuality gate
.github/workflows/release.ymlAutomated releases

Task Runner Convention

Prefer native build systems over justfile. Add a justfile only when project complexity demands orchestration beyond what the native tools provide.

LanguageNative Task RunnerWhen to Add justfile
Node/TSnpm scripts in package.jsonMonorepo orchestration, multi-step deploys
Rustcargo commandsMulti-crate workspaces, cross-compilation
GoMakefile + go commandsMulti-service repos, protobuf codegen
Pythonjustfile + uv runAlways (Python lacks a native task runner)
Terraformterraform CLIMulti-environment workspace management

Standard Task Interface

Every project should support these operations, regardless of how they’re invoked:

init    — install hooks, download deps
build   — compile / bundle
test    — run test suite
lint    — static analysis
fmt     — format code
check   — fmt + lint + test (quality gate)
run     — execute the project

Python Config (pyproject.toml)

  • [tool.ruff] line-length 100, select ["E","W","F","I","UP","B","SIM","RUF"]
  • [tool.pytest.ini_options] testpaths ["tests"], pythonpath ["src"]

CONTRIBUTING.md Template

Standard sections:

  1. Prerequisites — language runtime, build tools, GH_TOKEN
  2. Getting Started — git clone + language-specific init
  3. Development — language-specific check, test, fmt commands
  4. Commit Convention — conventional commits via sr commit
  5. Pull Requests — fork → branch → PR
  6. Code Style — brief, language-specific

License

Apache-2.0 for all repos. Exception: content-heavy sites (urmzd.com) may dual-license with CC BY-NC-ND 4.0 for content.

Documentation Philosophy

Skills vs Docs

Skills (skills/<name>/SKILL.md) are executable agent instructions — they tell AI agents how to do things: follow conventions, run workflows, use tools. They are operational, imperative, and agent-consumable.

Docs (docs/) are project documentation — they capture what was decided and why: design proposals, how-to guides, operational runbooks, architecture descriptions, and plans. They serve humans and agents alike as reference material.

Both exist in every project. Neither replaces the other.

File Placement

Root-level standard files (stay at project root):

  • README.md — human-facing (install, usage, examples)
  • AGENTS.md — AI-facing (architecture, interfaces, commands)
  • CONTRIBUTING.md — contributor onboarding
  • LICENSE, CODEOWNERS
  • llms.txt — LLM discovery (links to README, AGENTS.md, skill)
  • CHANGELOG.md — auto-generated by sr

All other documents go in docs/ — organized by purpose:

  • docs/guides/ — how-to guides and walkthroughs
  • docs/rfcs/ — design proposals and decision records
  • docs/plans/ — implementation and migration plans
  • docs/runbooks/ — operational procedures and incident response
  • docs/architecture/ — system design and diagrams
  • Add subdirectories as needed (e.g. docs/api/, docs/tutorials/)