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:

| Language | Skill | Key Tools | |----------|-------|-----------| | Rust | scaffold-rust | cargo, clippy, rustfmt, cross, crates.io | | Go | scaffold-go | go, golangci-lint, gofmt | | Python | scaffold-python | uv, ruff, pytest, ty | | Node/TS | scaffold-node | pnpm, biome, tsc | | Terraform | scaffold-terraform | terraform, AWS OIDC |

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

Standard Files (Every Project)

| File | Purpose | |------|---------| | README.md | Human-facing documentation (see write-readme) | | AGENTS.md | AI-facing project context (see configure-ai) | | LICENSE | Apache-2.0 (standard for all repos) | | CONTRIBUTING.md | How to contribute (see template below) | | CODE_OF_CONDUCT.md | Contributor Covenant 2.1 (see community-health) | | SECURITY.md | Vulnerability reporting policy (see community-health) | | .github/pull_request_template.md | Standard PR template (see community-health) | | .github/ISSUE_TEMPLATE/ | Bug report + feature request forms + config (see community-health) | | sr.yaml | Semantic release config | | .envrc | direnv config (per-language layout, env vars, dotenv) | | llms.txt | LLM-friendly project summary (see create-llms-txt) | | skills//SKILL.md | Agent skill instructions | | docs/ | Project documentation (guides/, rfcs/, plans/, runbooks/, etc.) | | .ai-memory/ | Tool-agnostic AI memory (see memory skill) | | .github/workflows/ci.yml | Quality gate | | .github/workflows/release.yml | Automated releases | | teasr.toml | Demo recording config (optional -- add for CLIs/visual output; see style-brand) | | showcase/ | Demo assets: demo.gif, demo.png, feature captures (optional -- add with teasr.toml) | | examples/ | Runnable example code (optional -- add for libraries/SDKs/configurable tools) | | spec/ | API specifications (optional -- add when project exposes/consumes a formal API) |

Task Runner Convention

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

| Language | Native Task Runner | When to Add justfile | |----------|-------------------|----------------------| | Node/TS | pnpm scripts in package.json | Monorepo orchestration, multi-step deploys | | Rust | cargo commands | Multi-crate workspaces, cross-compilation | | Go | Makefile + go commands | Multi-service repos, protobuf codegen | | Python | justfile + uv run | Always (Python lacks a native task runner) | | Terraform | terraform CLI | Multi-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
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// -- named by feature being demonstrated (e.g., agent/, streaming/, rag/)
• examples// -- named by use case for config-driven tools (e.g., petstore/, anthropic-messages/)

Entry Points by Language

| Language | Entry Point | Run Command | |----------|-------------|-------------| | Go | main.go | go run ./examples// | | Rust | main.rs | cargo run --example or standalone | | Python | main.py | uv run examples//main.py | | Node/TS | index.ts | npx tsx examples//index.ts |

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.

| File | Purpose | |------|---------| | teasr.toml | Demo recording config (see style-brand for template and theme) | | showcase/demo.gif | Hero demo animation (referenced in README at 80% width) | | showcase/demo.png | Hero demo screenshot (fallback if no GIF) | | showcase/.png | Feature-specific captures |

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

| Format | Extension | Example | |--------|-----------|---------| | OpenAPI | .yaml / .json | spec/openapi.yaml | | Protocol Buffers | .proto | spec/service.proto | | GraphQL | .graphql | spec/schema.graphql | | JSON Schema | .json | spec/config-schema.json |

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

| File | Source | When Required | |------|--------|---------------| | LICENSE | Copy of root LICENSE | Always (registries require per-package license) | | README.md | Minimal: crate name, description, link to parent workspace | Always (registries display per-package README) |

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//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)
• CODEOFCONDUCT.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 & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: urmzd
• Source: urmzd/dotfiles
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.