StackForge

Agent-friendly software project scaffolding CLI for apps, APIs, CLIs, and OSS packages.

StackForge requires Node.js 20 or newer. Its build, template checks, and CLI smoke tests run in CI on both Node.js 20 and the primary Node.js 22 runtime. The full contributor pnpm run release:check also requires Python 3.11 or newer to install and import the generated python-api projects. StackForge checks python3.13, python3.12, python3.11, then python3; set STACKFORGE_PYTHON to select another compatible interpreter explicitly.

Status

Early build. StackForge is release-scoped as a CLI-first tool first, with CrewCmd support treated as a later wrapper for orchestrator and sub-agent use.

CLI-first architecture

• stackforge CLI owns deterministic project generation.
• Humans and agents use the same local command surface.
• CrewCmd owns orchestration instructions, health checks, and capability routing later; it does not replace the CLI.
• OpenClaw agents should only run StackForge tasks on machines where the CLI is installed and verified.

Core commands

pnpm install
pnpm build
pnpm dev templates
pnpm dev init oss-cli my-tool --dry-run
pnpm dev init oss-cli my-tool
pnpm dev init oss-cli my-tool --prd ./docs/PRD.md --tasks ./docs/TASKS.md
pnpm dev init oss-cli my-tool --prd ./docs/PRD.md --taskbrief

The V1 release bar is a documented, deterministic command surface:

stackforge --version
stackforge templates
stackforge init oss-cli demo --dry-run
stackforge init oss-cli demo

GitHub repository creation

StackForge never creates a GitHub repository by default. To request GitHub creation, add --github-create; the first run is still a dry run for the GitHub and git publish commands so you can review them safely:

pnpm dev init oss-cli my-tool --github-create
pnpm dev init oss-cli my-tool --github-create --github-visibility public

After reviewing the printed github.command and github.publish.commands, rerun with --github-execute to create the repository through the GitHub CLI, initialize the generated project as a local git repo, create the initial scaffold commit, add origin, and push main:

pnpm dev init oss-cli my-tool --github-create --github-execute

--github-execute requires --github-create and cannot be combined with --dry-run. The default visibility is private; use --github-visibility public only when you intentionally want a public repository. For safety, git initialization and push only run for a fresh generated project directory, not an existing directory being overwritten with --force.

Safety model

StackForge is local-first and review-friendly:

• no hidden network calls
• no implicit GitHub creation
• no default LLM calls
• no autonomous merging or publishing
• no destructive overwrite behavior without explicit intent

Initial templates

• oss-cli: TypeScript CLI package
• next-app: Next.js application
• python-api: Python API service

Project directory and display names may contain spaces or punctuation. For the python-api template, StackForge normalizes that name for Python packaging: My API becomes distribution my-api and import module my_api. Import modules whose normalized name begins with a digit receive a leading underscore (for example, 123 API becomes _123_api). The original name remains the generated directory name and FastAPI display title.

Generated repositories include scripts/validate.sh as the default local verification path. It runs the repo's normal local package checks when they exist, including release:check, and only runs agent-qc ready when agent-qc is installed, so agent-qc stays optional.

The next-app scaffold ships an npm lockfile, .gitignore, next-env.d.ts, tsconfig.json, and an exact, reviewed Next.js toolchain. Its TypeScript metadata is complete before the first install or build, so framework commands do not need to rewrite the generated project. Use npm ci for a reproducible install and npm run audit to check the production dependency graph for high or critical advisories. The scaffold temporarily overrides Next.js's bundled postcss and sharp versions because the upstream range otherwise resolves releases with active advisories.

oss-cli projects also include ReleaseBox by default: releasebox.config.json, reviewed/tag-gated GitHub release workflows, and package smoke scripts. The generated release path creates GitHub Releases with attached tarballs while leaving npm and Homebrew publishing disabled until explicitly enabled.

Local planning docs

Use --prd <path> and --tasks <path> with stackforge init to copy local planning inputs into the generated repo as docs/PRD.md and docs/TASKS.md.

Taskbrief-generated tasks

If you want StackForge to derive docs/TASKS.md from a PRD after the scaffold is written, use --taskbrief:

pnpm dev init oss-cli my-tool --prd ./docs/PRD.md --taskbrief
pnpm dev init oss-cli my-tool --prd ./docs/PRD.md --taskbrief --taskbrief-workspace ./taskbrief

Rules:

• --taskbrief requires --prd
• --taskbrief cannot be combined with --tasks
• dry-run prints the planned taskbrief parse ... --format markdown --output docs/TASKS.md command without executing it
• execute mode runs taskbrief locally after StackForge writes the scaffold files
• if taskbrief is missing from PATH or exits non-zero, StackForge fails with a clear error

Release readiness docs

• pnpm run release:check runs build, tests, smoke, and package smoke.

• pnpm run package:smoke runs npm pack --dry-run and verifies the packed CLI, source, templates, release docs, README, and license are present.

• Release readiness guide

• Release checklist

• Release process

• OpenClaw agent workflow

PRD

See docs/PRD.md.