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

Language	Entry Point	Run Command
Go	main.go	go run ./examples/<name>/
Rust	main.rs	cargo run --example <name> or standalone
Python	main.py	uv run examples/<name>/main.py
Node/TS	index.ts	npx tsx examples/<name>/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/<feature>.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/<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/)