Urmzd Dotfiles Scaffold Project

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:

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

Standard Files (Every Project)

Task Runner Convention

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

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
record  . capture demo assets with teasr (when teasr.toml exists)

Examples Convention

Projects that expose a library, SDK, or configurable tool include an examples/ directory with self-contained, runnable examples.

Structure

• examples/basic/ -- simplest possible use case (always present when examples/ exists)
• examples/<feature>/ -- named by feature being demonstrated (e.g., agent/, streaming/, rag/)
• examples/<use-case>/ -- named by use case for config-driven tools (e.g., petstore/, anthropic-messages/)

Entry Points by Language

Each example must:

1. Work with minimal dependencies and zero configuration
2. Be referenced from the README Quick Start via fsrc (see write-readme)
3. Include a doc comment at the top explaining prerequisites and how to run it

Showcase & Demo Convention

Projects with a CLI or visual output include demo assets for the README.

The record task invokes teasr showme which reads teasr.toml and outputs to showcase/. For projects recording their own CLI, build first:

record: build
    teasr showme

Spec Convention

Projects that expose or consume a formal API place specifications in spec/:

For multi-version APIs, use subdirectories: spec/v1/, spec/v2/.

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 (Angular); see ship skill for AI-assisted authoring
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.

Sub-Package Convention

Publishable workspace members (sub-crates, sub-packages) must include their own documentation files for registry compliance (crates.io, npm, PyPI).

Minimal Sub-Package README Template

# {crate-name}

{description from Cargo.toml / pyproject.toml / package.json}

Part of the [{workspace-name}]({repository-url}) workspace.

## License

[Apache-2.0](../../LICENSE)

Skip examples/ workspace members -- they are not published independently.

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) -- these are GitHub-recognized community health files with special UI treatment:

• README.md human-facing (install, usage, examples) -- rendered on landing page
• CONTRIBUTING.md contributor onboarding -- linked on New Issue/PR pages
• SECURITY.md vulnerability reporting -- populates Security tab (template in community-health)
• CODE_OF_CONDUCT.md community standards -- community profile checklist (template in community-health)
• CHANGELOG.md auto-generated by sr
• LICENSE (no .md) -- must be at root for GitHub license detection
• CODEOWNERS -- auto-assigns PR reviewers
• AGENTS.md AI-facing (architecture, interfaces, commands)
• llms.txt LLM discovery (links to README, AGENTS.md, skill)
• .github/pull_request_template.md standard PR template (template in community-health)
• .github/ISSUE_TEMPLATE/ bug/feature issue forms + config (templates in community-health)

Nothing else belongs at root. Common files that should go in docs/ instead:

• ROADMAP.md → docs/roadmap.md (or use GitHub Projects/Issues)
• USAGE.md → docs/usage.md (or fold into README's Usage section)
• INSTALL.md → docs/install.md (or fold into README)
• ARCHITECTURE.md → docs/architecture/

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/)

Source: urmzd/dotfiles — distributed by TomeVault.