From 8cf30ed2192f25ead6e546e02d2e03bcf836aa8b Mon Sep 17 00:00:00 2001 From: Roger Chappel Date: Wed, 29 Apr 2026 10:56:30 +1000 Subject: [PATCH] docs: add stackforge release readiness guide --- README.md | 45 +++++++++++-- docs/release-checklist.md | 12 ++++ docs/release-readiness.md | 134 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 184 insertions(+), 7 deletions(-) create mode 100644 docs/release-readiness.md diff --git a/README.md b/README.md index f3b2046..9bfca8c 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,41 @@ # StackForge -Agent-friendly software project scaffolding CLI for apps, APIs, CLIs, and OSS packages. +Agent-friendly software project scaffolding CLI for apps, APIs, CLIs, and OSS +packages. ## Status -Early build. StackForge starts as a CLI-first tool and later gets wrapped by a CrewCmd-installable skill for orchestrator and sub-agent use. +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 +## 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 ```bash 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 ``` +The V1 release bar is a documented, deterministic command surface: + +```bash +stackforge --version +stackforge templates +stackforge init oss-cli demo --dry-run +stackforge init oss-cli demo +``` ### GitHub repository creation @@ -34,11 +54,15 @@ 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. -## Architecture +## Safety model -- `stackforge` CLI owns deterministic project generation. -- CrewCmd skill owns orchestration instructions, health checks, and node capability requirements. -- Agents should only run StackForge tasks on machines where the CLI is installed. +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 @@ -50,6 +74,13 @@ pnpm dev init oss-cli my-tool --github-create --github-execute Use `--prd ` and `--tasks ` with `stackforge init` to copy local planning inputs into the generated repo as `docs/PRD.md` and `docs/TASKS.md`. +## Release readiness docs + +- [Release readiness guide](docs/release-readiness.md) +- [Release checklist](docs/release-checklist.md) +- [Release process](docs/release-process.md) +- [OpenClaw agent workflow](docs/agent-workflow.md) + ## PRD See [docs/PRD.md](docs/PRD.md). diff --git a/docs/release-checklist.md b/docs/release-checklist.md index 965351b..410aea5 100644 --- a/docs/release-checklist.md +++ b/docs/release-checklist.md @@ -11,6 +11,18 @@ to the project, but do not skip verification and rollback notes. - [ ] Included changes are reviewable and merged. - [ ] Deferred changes are tracked separately. +### StackForge V1 gate + +For StackForge V1 or release-readiness review, also confirm: + +- [ ] `README.md` explains the CLI-first architecture. +- [ ] The CrewCmd-later boundary is documented and does not hide CLI ownership. +- [ ] Command examples cover `templates` and `init`, including `--dry-run`. +- [ ] OpenClaw agent usage expectations are documented. +- [ ] Safety constraints are documented: local-first behavior, no hidden network + calls, no implicit GitHub creation, and no autonomous merge. +- [ ] `docs/release-readiness.md` matches the current command surface. + ## 2. Changelog - [ ] `CHANGELOG.md` has an `Unreleased` section. diff --git a/docs/release-readiness.md b/docs/release-readiness.md new file mode 100644 index 0000000..93a804b --- /dev/null +++ b/docs/release-readiness.md @@ -0,0 +1,134 @@ +# StackForge Release Readiness + +This guide defines what must be true before StackForge should be presented as a +reviewable V1 scaffold CLI. + +## CLI-first architecture + +StackForge is intentionally CLI-first. + +- `stackforge` is the deterministic engine that lists templates, previews + scaffold output, and writes repositories locally. +- Humans and agents interact with the same command surface. +- CrewCmd is a later wrapper, not the source of truth for generation logic. +- OpenClaw agents should call the CLI only on machines where StackForge is + already installed and verified. + +That boundary keeps the core product testable without depending on orchestration +state. + +## V1 commands + +Release readiness for V1 is anchored to a small command surface: + +```bash +stackforge --version +stackforge templates +stackforge init oss-cli demo --dry-run +stackforge init oss-cli demo +``` + +Expected behavior: + +- `--version` returns the installed CLI version. +- `templates` lists the currently supported templates. +- `init ... --dry-run` prints a deterministic plan without writing files. +- `init ...` writes the scaffold locally and avoids hidden network steps. + +`launch` can remain documented as a follow-on workflow, but V1 readiness should +not depend on CrewCmd-driven orchestration being complete. + +## Command examples + +### Inspect available templates + +```bash +pnpm dev templates +``` + +### Preview a scaffold without writing files + +```bash +pnpm dev init oss-cli my-tool --dry-run +``` + +### Generate a local scaffold + +```bash +pnpm dev init oss-cli my-tool +``` + +### Release verification commands + +```bash +pnpm check +pnpm build +pnpm check:templates +pnpm smoke:init +``` + +## Safety model + +StackForge should be safe by default. + +- No hidden network calls. +- No implicit GitHub repository creation. +- No default LLM calls. +- No autonomous merging or publishing. +- File generation must stay deterministic and reviewable. +- Destructive overwrite behavior must require explicit operator intent. + +The release bar is not just "it scaffolds"; it must scaffold in a way that is +predictable enough for humans and agents to trust. + +## OpenClaw agent workflow + +OpenClaw is an execution environment around StackForge, not a replacement for +it. + +1. Verify the node or host has the StackForge CLI installed. +2. Run `stackforge templates` or a dry run first to confirm the requested path. +3. Use `stackforge init ... --dry-run` in planning or review-heavy flows. +4. Run `stackforge init ...` only after the target repo name and template are + confirmed. +5. Hand the generated repository back to the normal branch, commit, PR, and + review workflow. + +This keeps agent usage grounded in the same deterministic CLI behavior a human +maintainer would use locally. + +## CrewCmd-later boundary + +CrewCmd support is valuable, but it is explicitly a later wrapper. + +For V1, release-ready means: + +- the CLI works on its own +- commands are documented +- safety constraints are documented +- agent usage expectations are documented +- verification scripts pass + +It does **not** require: + +- CrewCmd packaging to be complete +- orchestration-specific automation to be the only entry point +- StackForge to replace OpenClaw, CrewCmd, or GitHub review flows + +## V1 release checklist + +Use this checklist with the general release process docs before opening a V1 +release PR. + +- [ ] README explains the CLI-first architecture and CrewCmd-later boundary. +- [ ] README or docs include working command examples for `templates` and + `init`. +- [ ] V1 command surface is limited to documented, supported behavior. +- [ ] Safety expectations are documented: local-first, no hidden network calls, + no implicit GitHub creation, no autonomous merge. +- [ ] OpenClaw agent workflow is documented for dry runs and local execution. +- [ ] `pnpm check` passes. +- [ ] `pnpm build` passes. +- [ ] `pnpm check:templates` passes. +- [ ] `pnpm smoke:init` passes. +- [ ] Any deferred CrewCmd work is clearly marked as post-V1.