agent-project-bootstrap

Ship a FOSS app with an agent that already knows the rules.

Click Use this template, run init, then /tour. One AGENTS.md for every IDE; CI and security on by day one.

• One spec — Cursor, Windsurf, Claude, Copilot, Cline, and others follow the same contract
• Tour + coach — /tour, /coach, docs/FIRST_30_DAYS.md
• Gates in English — what failed / what to run
• Security default — Dependabot, CodeQL, secret scanning; no tracking
• Golden Paths — Web, Python, Android, Node (optional stacks too)

Obtain / bugs / vulns / patches: GitHub · SUPPORT.md · SECURITY.md · CONTRIBUTING.md.

Also: Quick Start · Architecture · Stacks · Security · Agent shortcuts · Start here

---

Getting started

Quick Start

1. Click Use this template on GitHub to create your project repo. Or open this template in GitHub Codespaces (devcontainer included).

2. Clone and run the init script:

   # Linux / macOS / WSL
   ./scripts/init-project.sh
   
   # Windows PowerShell
   .\scripts\init-project.ps1

3. Open your agent. First walk: /tour or docs/help/TOUR.md. Cline (free): docs/help/CLINE.md.

   Read @docs/START_HERE.md and @docs/INITIALIZATION_PROMPT.md. Follow BUILD_PLAN Sequential.
   

4. Shortcuts: docs/help/BATCH_COMMANDS.md — /tour · /bootstrap · /verify · /build · /ship.

Non-interactive (CI / scripts):

./scripts/init-project.sh \
  --non-interactive \
  --stack web \
  --project-name "My App" \
  --purpose "Offline-first notes" \
  --license MIT

Architecture

This is a GitHub Template Repository, not a separate project-generator CLI. Use this template copies the tree; scripts/init-project.sh (or .ps1) customizes it.

flowchart LR
  Template[Template repo] --> Clone[Use this template]
  Clone --> Pre[Preflight: git + Python]
  Pre --> Init[init-project]
  Init --> Post[Post hooks]
  Post --> Manifest[bootstrap.config.json]
  Post --> Adapters[AGENTS.md adapters]
  Post --> Check[PROJECT_CHECKLIST.md]

Loading

AGENTS.md is the agent source of truth. scripts/bootstrap-lifecycle.sh --sync-adapters writes thin pointers for Cursor, Claude Code, Copilot, Windsurf, Antigravity/Gemini, Aider, Cline, and Continue. Product intent lives in docs/spec.md; task breakdown in docs/plan.md and BUILD_PLAN.md.

Feature summary

Capability	What ships
Agent spec	AGENTS.md — overview, env, gates, test-first, security
Multi-agent adapters	Cursor, Claude, Copilot, Windsurf, Gemini/Antigravity, Aider, Cline, Continue
First-run tour	/tour and docs/help/TOUR.md
UX/UI law	docs/ux-ui-guidelines.md (how we build UI); /ux-review checks the same bar
Coach layer	docs/BEST_PRACTICES.md, docs/FIRST_30_DAYS.md, /coach
Readable gates	Plain-English feature-gate hints; bash scripts/verify.sh
Spec-driven	docs/spec.md, docs/plan.md, docs/features/_template.md
Security by default	SECURITY.md, Dependabot, CI, CodeQL, secret scanning, Scorecard
Governance	Issue + PR templates, SUPPORT.md, CITATION.cff, MIT / Apache-2.0
Lifecycle	Preflight, bootstrap.config.json, PROJECT_CHECKLIST.md
Editor DX	.vscode/tasks.json, Codespaces / devcontainer, optional justfile

What gets generated

After Use this template and scripts/init-project.sh (or .ps1):

File	When
bootstrap.config.json	Post-init manifest (name, stack, license, hooks)
PROJECT_CHECKLIST.md	Definition of Done checklist
AGENTS.md project card	Stamped product / purpose / stack
.cursor/rules/main.mdc	Cursor adapter (from AGENTS.md)
CLAUDE.md	Claude Code adapter
.github/copilot-instructions.md	GitHub Copilot adapter
GEMINI.md	Antigravity / Gemini pointer (never real rules)
.windsurf/rules/agents-pointer.md	Windsurf pointer
.clinerules/AGENTS.md, .clinerules/workflows/, CONVENTIONS.md, .continue/rules/agents.md	Cline pointer + workflows; Aider / Continue pointers
LICENSE	Rewritten only when --license Apache-2.0
Shipped in the template (not generated): docs/spec.md, docs/plan.md, docs/BEST_PRACTICES.md, docs/FIRST_30_DAYS.md, docs/AGENT_PORTABILITY.md, docs/help/TOUR.md, SUPPORT.md, CITATION.cff, env.schema.json, .devcontainer/, .vscode/tasks.json, .agent/memory/, .pre-commit-config.yaml, CI/security workflows, issue/PR templates. Optional .github/FUNDING.yml when a donation URL is set. Optional just verify if just is installed — CI still calls scripts/verify.sh directly.

Agent shortcuts (cheat sheet)

docs/help/BATCH_COMMANDS.md — shortcut recipes. In Cursor type /. In any other IDE, paste the matching docs/help/ file. Print: open docs/help/batch-commands-print.html in a browser and use Print.

• /tour — 10-minute first-run walk (docs/help/TOUR.md)
• /ux-review — score shipped UI against docs/ux-ui-guidelines.md (same law used while building)
• /bootstrap — new project Sprint 0, then the tour
• /coach — next action and the industry why
• /ideas — ranked in-scope backlog (does not implement)
• /allideas — complete in-scope dump to fill BUILD_PLAN (does not implement until you say board)
• /upgrade — child: plan template catch-up without overwriting the app; this template: upgrade sim
• /build — plan and implement a feature
• /verify — checks before merge
• /ship — publish a release to GitHub

Bookmark the cheat sheet for when you come back after a break. Print the novice list from the HTML file above.

Stack Selection (Sprint 0)

During init-project, choose web, python, android, multi, or none (keep all).

Active modules are synced to AGENT_MEMORY.md and recorded in .cursor/stack-selection.json.

---

How agents work

What's Included

Component catalog — onboarding, memory, security, examples, tooling

Onboarding & agents

Initialization prompt

docs/INITIALIZATION_PROMPT.md

Agent routing

docs/START_HERE.md, docs/CURSOR_MODES.md, docs/AGENT_PORTABILITY.md, AGENTS.md

First-run tour & coach

docs/help/TOUR.md (/tour), docs/BEST_PRACTICES.md, docs/FIRST_30_DAYS.md (/coach)

Agent shortcuts

docs/help/BATCH_COMMANDS.md — /tour, /bootstrap, /coach, /verify, /build, /ship

Sprint task board

BUILD_PLAN.md (active board); archived sprints in COMPLETED_TASKS.md

Memory & decisions

Workspace memory

AGENT_MEMORY.md, DECISION_LOG.md, KNOWLEDGE_BASE.md

Security & operations

Security & privacy

SECURITY.md, docs/SECURITY_TRIAGE.md, docs/THREAT_MODEL.md, docs/PRIVACY.md

Operations

docs/RUNBOOK.md

License attribution

THIRD_PARTY_LICENSES.md, LICENSE

Examples & tooling

Stack modules

modules/{web,python,android,lightroom,rust,go}/MODULE.md

Golden Path examples

examples/{web,python,android,node}/; optional lightroom/, rust/, go/ — see docs/OPTIONAL_STACKS.md

Agent documentation

docs/ — prompts, security, design guide (not the public website)

Public website source

examples/web/ (Vite PWA source; see docs/WEB_PROJECT_LAYOUT.md)

GitHub Pages deploy

.github/workflows/pages.yml → examples/web/dist (Actions artifact)

CI guardrails

.github/workflows/ (incl. OpenSSF Scorecard weekly)

Cursor rules

.cursor/rules/*.mdc (incl. cursor-modes.mdc, batch-commands.mdc — see docs/CURSOR_MODES.md and docs/help/BATCH_COMMANDS.md)

BUILD_PLAN Labels

Every task carries an owner label for filtering automated vs human work.

Status markers: 🔲 open · ✅ done · ❌ blocked — use emoji on all checklist rows (not - [ ] checkboxes) so state is clear in Markdown source and Preview. See BUILD_PLAN.md legend.

Tip

Filter tasks by owner: grep '\[AGENT\]' BUILD_PLAN.md (also HUMAN, ADB, AUTO).

Label	Owner	When to use
	Coding agent	Code, docs, scaffolding, tests, CI
	Human developer	Approvals, credentials, GitHub settings
	Human (Android)	Device testing, F-Droid submission
	CI/scripts	GitHub Actions, Dependabot, pre-commit

grep '\[AGENT\]' BUILD_PLAN.md
grep '\[HUMAN\]' BUILD_PLAN.md
grep '\[ADB\]' BUILD_PLAN.md
grep '\[AUTO\]' BUILD_PLAN.md

This repo’s live board is BUILD_PLAN.md. Child products start from BUILD_PLAN_TEMPLATE.md (same layout, copied onto BUILD_PLAN.md at init). Each file opens with a remaining-item tally. Completed sprints: COMPLETED_TASKS.md.

GitHub Pages Demo

The examples/web PWA deploys to GitHub Pages on push to main (workflow: .github/workflows/pages.yml). The build sets VITE_BASE_PATH for project-site hosting with no analytics or tracking scripts.

Warning

docs/ is not your website. Agent instructions live in docs/; only examples/web/dist/ is deployed. Set Pages source to GitHub Actions, not "Deploy from /docs". See docs/WEB_PROJECT_LAYOUT.md.

---

Operations

Template Update Checker

Upstream release checks — intervals, manual commands, devcontainer

Child repos can check for new upstream template releases on GitHub.

Configure in .template-update.json:

off

Disabled

daily

Check at most once per day

weekly (default)

Check at most once per week

monthly

Check at most once per month

on_session

Check every devcontainer/session start

notify_method supports stdout only (banner printed to terminal).

Change interval: edit .template-update.json or re-run the init script.

Manual check:

bash scripts/check-template-updates.sh
# or
pwsh scripts/check-template-updates.ps1

Runs automatically on devcontainer start. When a new version is available, see docs/UPGRADING_FROM_TEMPLATE.md.

The devcontainer also runs check-file-encoding.sh on start, includes the GitHub CLI (gh) for validate-workflow-actions.sh, and prints a reminder to run check-github-ci.sh --wait 300 after pushing to main.

GitHub CI Gate (post-push)

Post-push scripts — CI poll, repo setup, pre-release gate

After pushing workflow or dependency changes to main, poll required workflows:

bash scripts/check-github-ci.sh --wait 300
# Windows:
pwsh scripts/check-github-ci.ps1 -WaitSeconds 300

Required status checks (branch protection via scripts/setup-github-repo.sh): CI, Security Scan, CodeQL, Repo Hygiene, Feature Gate, Template Upgrade Simulation (Windows). check-github-ci polls the three workflow rollups; Repo Hygiene, Feature Gate, and the Windows upgrade-sim are jobs inside the CI workflow.

One-time repo security setup (Dependabot alerts, private reporting, branch protection):

bash scripts/setup-github-repo.sh
# Windows:
pwsh scripts/setup-github-repo.ps1

Before any version bump or release tag:

bash scripts/pre-release-gate.sh
# Windows:
pwsh scripts/pre-release-gate.ps1

Security

Dependabot alerts (one-time setup)

Important

[HUMAN] Enable Dependabot alerts and Dependabot security updates under Settings → Code security and analysis.

See docs/SECURITY_TRIAGE.md for the full setup and weekly triage checklist.

Report vulnerabilities via SECURITY.md (private reporting preferred).

Community standards: CODE_OF_CONDUCT.md

Weekly CVE triage — recommended Monday checklist

[HUMAN] runs a weekly triage pass (recommended: Monday):

1. Review Dependabot alerts (Critical/High first)
2. Triage open Dependabot PRs (fix / defer / dismiss)
3. Confirm Trivy + CodeQL CI green after merges

---

Stacks & layout

Supported Stacks

Stack	Guide	Example
	modules/web/MODULE.md	examples/web/
	modules/python/MODULE.md	examples/python/
	modules/android/MODULE.md	examples/android/
	modules/lightroom/MODULE.md	examples/lightroom/

Optional stacks: — optional stacks in docs/OPTIONAL_STACKS.md.

Machine-readable catalog: TEMPLATE_INDEX.json

Repository Layout

Folder map — docs, modules, examples, scripts

docs/           Agent docs only (NOT the public website) — see docs/WEB_PROJECT_LAYOUT.md
modules/        Stack-specific agent rules (activate matching stack only)
examples/       Golden Path reference implementations
examples/web/   PWA source; dist/ published via GitHub Actions
scripts/        Init, update checker, validation
.cursor/rules/  Persistent Cursor agent directives
.github/        CI workflows, Dependabot, issue templates

---

Project meta

Contributing

MIT licensed. See CONTRIBUTING.md. Questions vs bugs vs vulns: SUPPORT.md.

Template maintainers: docs/MAINTAINING_THE_TEMPLATE.md

GitHub About

Repo description draft for the short About preview: docs/GITHUB_ABOUT.md

Maintainer Release

Current template version: 1.10.0 (see .template-version, Release Please, and scripts/pre-release-gate.sh).