OSS Project

Bootstrap, polish, and publish open-source projects with AI-first documentation and governance standard. Designed for AI-first development where documentation is the primary interface for agent contributors.

Origin: Extracted from a real AI-powered sprite restyling package and generalized as a reusable pattern for rapid PoC shipping.

Sources & Attribution

Source	What	URL
dec0dOS/amazing-github-template	`.github/` structure, community files, workflows	https://github.com/dec0dOS/amazing-github-template
othneildrew/Best-README-Template	README section conventions	https://github.com/othneildrew/Best-README-Template
anthropics/skills `doc-coauthoring`	Documentation co-authoring workflow	https://github.com/anthropics/skills/tree/main/skills/doc-coauthoring
gitleaks/gitleaks-action	Secrets scanning workflow	https://github.com/gitleaks/gitleaks-action

Usage

# Scaffold a new project
/oss-project init --name my-project --lang typescript

# Add missing docs to an existing project
/oss-project audit --path ./my-project

# Polish an existing repo for open-source publishing
/oss-project polish --path ./my-project

What It Creates

my-project/
├── AGENTS.md              # AI agent entry point (build, conventions, gotchas)
├── CONTEXT.md             # Static architecture overview + reading order
├── CONTRIBUTING.md        # Dev workflow, code style, testing philosophy
├── DECISIONS.md           # Architecture Decision Log (DEC-001, DEC-002, ...)
├── ROADMAP.md             # Priorities with acceptance criteria
├── README.md              # Product-level docs with badges
├── CHANGELOG.md           # Keep a Changelog format, populated from git history
├── CODE_OF_CONDUCT.md     # Contributor Covenant
├── SECURITY.md            # Vulnerability reporting
├── RELEASING.md           # Release runbook (Changesets)
├── LICENSE                # MIT (default)
├── .editorconfig          # Consistent formatting across editors
├── .gitattributes         # Line-ending normalization
├── .nvmrc / .node-version # Node.js version pinning (if applicable)
├── .github/
│   ├── workflows/
│   │   ├── ci.yml         # Build + typecheck + test + Gitleaks secret detection
│   │   └── release.yml    # Changesets auto-release + npm publish with provenance
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md  # Structured bug report (env, repro steps, logs)
│   │   └── feature_request.md  # Problem → solution → alternatives
│   └── pull_request_template.md  # Checklist + decision impact + contributor type
└── ...

All templates are in templates/ and use {{PLACEHOLDER}} syntax for project-specific values.

README Best Practices (Baked In)

The README template follows current OSS best practices:

Centered header with project name + one-line description
Badge row (npm version, license, TypeScript, CI status)
"How It Works" -- visual pipeline diagram before any details
Feature list with emoji markers for scannability
Install + Quick Start -- copy-pasteable within 30 seconds
Environment variables table -- not buried in prose
CLI reference table -- command + description, no walls of text
Programmatic usage -- import example for library consumers
CI & Security section -- signals trust and professionalism
Roadmap link -- points to ROADMAP.md (single source of truth)
Contributing link -- split by audience (AI agents → AGENTS.md, humans → CONTRIBUTING.md)
Footer with npm + GitHub + Issues links

README rules:

Lead with what, not how. First sentence = value proposition.
Badges: only include meaningful ones (CI status, version, license). No vanity badges.
Code examples must be copy-pasteable and working.
No "Table of Contents" for READMEs under 200 lines.
Prefer a visual (screenshot, diagram, GIF) if the project has UI.

CHANGELOG (Keep a Changelog)

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- Initial public release

Rules: Populate from actual git history -- don't invent entries. Group by: Added, Changed, Deprecated, Removed, Fixed, Security. Link version headers to GitHub compare URLs when possible.

Additional Files (Always Include)

.editorconfig

root = true

[*]
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
charset = utf-8

[*.{js,ts,jsx,tsx,json,yml,yaml,md}]
indent_style = space
indent_size = 2

[Makefile]
indent_style = tab

.gitattributes

* text=auto eol=lf

.nvmrc / .node-version (Node.js projects)

Pin the runtime version to match the project's target.

CI Pipeline (Security-First)

The CI template includes:

Build + Typecheck -- catches type errors before merge
Gitleaks secret detection -- scans full git history for leaked API keys, tokens, passwords
Release automation -- Changesets creates release PRs, publishes to npm with provenance
Branch protection ready -- designed for required status checks on main

Core Principles

1. AGENTS.md Is The Front Door

Every AI agent starts here. It must contain:

Build & test commands (copy-pasteable)
Architecture overview (10 files or less)
Code conventions (strict, no ambiguity)
Key decisions summary (with links to DECISIONS.md)
Gotchas (things that will waste an agent's time)
Reading order for deeper context

Rule: If an agent can't orient itself from AGENTS.md alone, it's incomplete.

2. Documentation As Interface

In AI-first development, docs are not afterthoughts -- they are the API.

File	Purpose	Update Frequency
`AGENTS.md`	Agent entry point	Every architecture change
`CONTEXT.md`	Static background	Rarely (module map changes)
`DECISIONS.md`	Living decision log	Every non-trivial decision
`ROADMAP.md`	Priorities + acceptance criteria	When items change status
`CONTRIBUTING.md`	Dev workflow + testing	When process changes

Rule: Inline TSDoc in source files is the source of truth for implementation. Markdown docs are for orientation and decisions.

3. Lean Governance (Founder Mode)

For early-stage projects:

## Governance

- **Owner / decision authority**: @<founder>
- **AI implementation agent**: @<agent>

Decision rules:
- Non-trivial changes require a DEC-xxx entry in DECISIONS.md
- New decisions start as `Status: proposed`
- Only @<founder> marks decisions as `accepted`

Scale governance only when the project demands it. Don't cargo-cult.

4. Decision Log Format

Every architecture decision gets a structured entry:

## DEC-001: <Title>

- **Status**: proposed | accepted | superseded
- **Date**: YYYY-MM-DD
- **Owner**: @<founder>
- **Proposed-by**: @<agent-or-human>
- **Accepted-by**: (pending)
- **Decision**: <one sentence>
- **Rationale**: <why this over alternatives>
- **Supersedes**: DEC-00Y (optional)
- **Affected modules**:
    - `src/...`

Rule: Every PR must declare decision impact (none / implements existing / proposes new).

5. Roadmap With Teeth

Every roadmap item must have:

Priority (High / Medium / Low)
Status (Not started / In progress / Done)
Why -- the problem it solves
Constraints -- non-negotiable boundaries
Approach -- high-level how
Acceptance criteria -- measurable definition of done

Vague roadmap items ("improve performance") are not allowed.

6. Tests As Specification

Tests serve two purposes:
1. Verify correctness
2. Specify behavior for the next agent

An agent reading tests should understand what the code is supposed to do. No manual verification steps. Everything automatable.

7. PR Checklist (Enforced)

Every PR:

typecheck -- zero errors
build -- compiles clean
test -- all pass
Changeset added (unless docs-only)
TSDoc on new/changed public API
Tests for new/changed behavior
Decision impact declared

Phase 3: Repo Description & Tags

After all files are created, output (NOT as a file -- print to the user) a suggested:

Description: <one-liner, max 350 chars -- what it does + key differentiator>

Topics/Tags:
  - <tag1>
  - <tag2>
  - ...
  (6-12 tags: include language, framework, domain, and discoverability terms)

Website: <docs URL or homepage if applicable>

Tag rules:

Always include: primary language (e.g., typescript), framework (e.g., react), project type (e.g., cli, library, framework)
Add domain tags (e.g., ai, devtools, automation)
Use lowercase, hyphenated format
6-12 tags total

Audit Mode

When running on an existing project, the skill checks for:

❓ Missing AGENTS.md → Generate from source analysis
❓ Missing CONTEXT.md → Generate architecture overview
❓ Missing DECISIONS.md → Create with governance template
❓ Missing ROADMAP.md → Create with priority template
❓ Missing CONTRIBUTING.md → Generate from detected toolchain
❓ Missing CHANGELOG.md → Generate from git history
❓ Missing CI workflows → Generate based on language/framework
❓ Missing PR template → Add standard template
❓ Missing issue templates → Add bug + feature templates
❓ Missing .editorconfig → Add standard config
❓ Missing .gitattributes → Add line-ending normalization

Language Support

Templates auto-detect and adapt to:

Language	Build	Test	Lint	Package Manager
TypeScript	`tsc`	`vitest`	strict mode	`pnpm`
Python	`uv build`	`pytest`	`ruff`	`uv`
Rust	`cargo build`	`cargo test`	`clippy`	`cargo`
Go	`go build`	`go test`	`golangci-lint`	`go mod`

Philosophy

"Es zählt nicht, wer den schönsten Code schreibt. Es zählt, wer die meisten Menschen inspiriert." -- a wise co-founder

This skill exists because shipping 10 well-documented PoCs beats one undocumented monolith. Every new project deserves a clean start with the right structure from day one.

Polish Principles

Don't over-document -- A 50-line CLI doesn't need SECURITY.md and 4 issue templates. Scale documentation to project size.
Real content only -- Never leave [TODO] or Lorem ipsum. Either fill it in from the codebase or skip the section.
Badges must work -- Only add badges for things that are actually set up (CI, npm, license).
Match the project's voice -- A fun side project gets casual tone; an enterprise library gets professional tone.
Git history is truth -- Populate CHANGELOG from actual commits, not imagination.
Ask when uncertain -- License choice, project name, target audience -- ask the user rather than guessing.

oss-project

SKILL.mdskills/oss-project/SKILL.md