noobygains/godmode/project-bootstrap

Project Bootstrap

A project's foundation is cheapest on day one and most expensive the day after the first feature lands. Before any feature code, the repository gets version control hygiene, a formatter, a linter, a test runner with one passing test, CI that runs them, and safe handling of configuration and secrets. The foundation is part of the first commit, not a later clean-up.

The Prime Directive

NO FEATURE CODE UNTIL THE FOUNDATION RUNS GREEN IN CI

No exceptions. No workarounds. No shortcuts.

"Runs green" means you ran format check, lint, type check (where the language has one) and tests locally, they passed, and the same commands are in a CI workflow.

When to Use

Required:

• A new project, repository, package, service or CLI.
• "Just get something running" and "it's only a prototype": prototypes are kept more often than they are thrown away.
• An inherited project with no .gitignore, no formatter, no tests or no CI.
• Adding a new language or package to a monorepo.

Skip:

• A throwaway experiment the user has explicitly said will be deleted, kept out of any shared repository.
• An existing project whose foundation already runs green; follow its conventions with godmode:codebase-conventions instead of re-bootstrapping it.

The Protocol

1. Probe the environment. Invoke godmode:environment-awareness and record the OS, shell, runtimes and the package manager the user prefers. Scaffold only with tools that are installed or that the user agrees to install.

1. Classify the project with the table below. The class decides the blueprint in references/templates.md. Mixed projects (an API with a web front end) take one blueprint per deployable part.

1. Check current tool versions and commands before writing config. Invoke godmode:grounding for every tool you are about to configure. Config formats change between majors (ESLint moved to eslint.config.js, golangci-lint v2 requires version: "2"), so the dated notes in the templates file are a starting point that you refresh, not a source of truth. Record what you verified and the date.

1. Initialise version control first. git init, a .gitignore for the language plus the universal entries below, and a .gitattributes that fixes line endings. The .gitignore must exclude .env before any .env file exists.

1. Use the ecosystem's own initialiser (npm create, uv init, cargo new, go mod init) instead of hand-writing manifests, then commit the lockfile it produces.

1. Wire the foundation: formatter, linter, type checker, test runner. Write one real test that passes, and run each tool once so its output proves it works. Save each check as a named script or task (npm run lint, make test, uv run pytest) so humans, agents and CI call the same command.

1. Add CI that runs exactly those scripts on push and pull request, with read-only default token permissions. Use the minimum workflow in the templates file and pin third-party actions as described there.

1. Add configuration handling. A committed .env.example lists every variable with a placeholder and a comment; real values live only in an ignored .env or a secret manager. Invoke godmode:security-protocol for anything that holds credentials.

1. Write the README with three things: what the project is, how to install it, and the exact commands to run, test and build it.

1. Prove it. Run the full check locally from a clean clone (or after deleting dependency and build directories), then push and confirm the CI run is green. Paste or link the evidence before you report the foundation as done, per godmode:completion-gate.

Project Classes

The Universal Foundation

Every class gets all of these:

Universal `.gitignore` entries: dependency directories (node_modules/, .venv/, target/), build output (dist/, build/, out/), environment files (.env, .env.*, with !.env.example), logs (*.log), OS files (.DS_Store, Thumbs.db), and editor directories unless the team shares settings on purpose.

Line endings: * text=auto in .gitattributes, plus *.sh text eol=lf for shell scripts so they run on Linux and in Git Bash.

Directory Principles

• Organise by feature, not by file type. orders/ holding its routes, service, model and tests beats top-level controllers/, services/, models/. Architecture choices belong to godmode:system-design.
• Keep core logic apart from the delivery layer. A CLI's argument parsing, an API's HTTP handlers and a UI's components call into plain modules that tests can exercise without the framework.
• Co-locate unit tests (payment.ts beside payment.test.ts) unless the ecosystem convention says otherwise (Rust integration tests in tests/, Python projects often in tests/). End-to-end tests get their own directory.
• One obvious entry point per deployable, named in the README.
• Scripts in `scripts/`, each runnable on every platform the team uses, or documented as POSIX-only.
• Follow the framework's layout when a framework imposes one; do not fight a generator's structure.

Dependency Governance

Before adding any dependency, answer these and keep the answers in the commit message or PR description:

1. Need: could you write it in under 50 clear lines? If so, write it.
2. Health: recent releases, responsive maintainers, more than one maintainer for anything critical.
3. Weight: how many transitive dependencies it brings in, and its install and bundle size.
4. Risk: known vulnerabilities (run the ecosystem's audit), licence compatible with the project, install scripts that run code on install.
5. Fit: does an existing dependency already cover it?

Always: commit the lockfile; install in CI with the frozen-lockfile mode (npm ci, pnpm install --frozen-lockfile, uv sync --locked); run the dependency audit in CI; add automated update pull requests so upgrades arrive in small steps. Treat a new dependency as a supply-chain decision (godmode:security-protocol).

Cognitive Traps

Guardrails

Never:

• Write feature code before the foundation runs green locally and in CI.
• Commit a .env, credentials, build output or dependency directories.
• Copy a tool version or config format from memory or from an old template without checking it today.
• Mix two package managers or two lockfiles in one project.
• Add a dependency without the governance answers.

Always:

• Probe the environment and classify the project first.
• Use the ecosystem's initialiser and commit the lockfile.
• Give every check a named script, and make CI call those scripts.
• Write one real passing test on day one.
• Show the green CI run before calling the bootstrap done.

Connections

• godmode:environment-awareness: runs first; the scaffold uses the tools and package manager it found.
• godmode:grounding: verifies every tool version, config format and CI action before it is written.
• godmode:system-design: decides architecture, hosting and technology choices when they are open questions.
• godmode:quality-gates: adds coverage ratchets, size budgets and the stricter gates once the foundation exists.
• godmode:security-protocol: secrets handling, dependency audit and supply-chain rules.
• godmode:test-first: every feature after the bootstrap starts with a failing test.
• godmode:completion-gate: the green CI run is the evidence the bootstrap is finished.