Skip to content

Commit 28162f8

Browse files
rogerchappelrogerchappel
authored
Merge pull request #7 from rogerchappel/agent/stackforge-release-readiness-docs-document-cli-first-architecture-comman
docs: add StackForge release readiness docs
2 parents d3f86a5 + 8cf30ed commit 28162f8

3 files changed

Lines changed: 184 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,41 @@
11
# StackForge
22

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

56
## Status
67

7-
Early build. StackForge starts as a CLI-first tool and later gets wrapped by a CrewCmd-installable skill for orchestrator and sub-agent use.
8+
Early build. StackForge is release-scoped as a CLI-first tool first, with
9+
CrewCmd support treated as a later wrapper for orchestrator and sub-agent use.
810

9-
## CLI
11+
## CLI-first architecture
12+
13+
- `stackforge` CLI owns deterministic project generation.
14+
- Humans and agents use the same local command surface.
15+
- CrewCmd owns orchestration instructions, health checks, and capability
16+
routing later; it does not replace the CLI.
17+
- OpenClaw agents should only run StackForge tasks on machines where the CLI is
18+
installed and verified.
19+
20+
## Core commands
1021

1122
```bash
1223
pnpm install
1324
pnpm build
1425
pnpm dev templates
1526
pnpm dev init oss-cli my-tool --dry-run
27+
pnpm dev init oss-cli my-tool
1628
pnpm dev init oss-cli my-tool --prd ./docs/PRD.md --tasks ./docs/TASKS.md
1729
```
1830

31+
The V1 release bar is a documented, deterministic command surface:
32+
33+
```bash
34+
stackforge --version
35+
stackforge templates
36+
stackforge init oss-cli demo --dry-run
37+
stackforge init oss-cli demo
38+
```
1939

2040
### GitHub repository creation
2141

@@ -34,11 +54,15 @@ pnpm dev init oss-cli my-tool --github-create --github-execute
3454

3555
`--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.
3656

37-
## Architecture
57+
## Safety model
3858

39-
- `stackforge` CLI owns deterministic project generation.
40-
- CrewCmd skill owns orchestration instructions, health checks, and node capability requirements.
41-
- Agents should only run StackForge tasks on machines where the CLI is installed.
59+
StackForge is local-first and review-friendly:
60+
61+
- no hidden network calls
62+
- no implicit GitHub creation
63+
- no default LLM calls
64+
- no autonomous merging or publishing
65+
- no destructive overwrite behavior without explicit intent
4266

4367
## Initial templates
4468

@@ -50,6 +74,13 @@ pnpm dev init oss-cli my-tool --github-create --github-execute
5074

5175
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`.
5276

77+
## Release readiness docs
78+
79+
- [Release readiness guide](docs/release-readiness.md)
80+
- [Release checklist](docs/release-checklist.md)
81+
- [Release process](docs/release-process.md)
82+
- [OpenClaw agent workflow](docs/agent-workflow.md)
83+
5384
## PRD
5485

5586
See [docs/PRD.md](docs/PRD.md).

‎docs/release-checklist.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,18 @@ to the project, but do not skip verification and rollback notes.
1111
- [ ] Included changes are reviewable and merged.
1212
- [ ] Deferred changes are tracked separately.
1313

14+
### StackForge V1 gate
15+
16+
For StackForge V1 or release-readiness review, also confirm:
17+
18+
- [ ] `README.md` explains the CLI-first architecture.
19+
- [ ] The CrewCmd-later boundary is documented and does not hide CLI ownership.
20+
- [ ] Command examples cover `templates` and `init`, including `--dry-run`.
21+
- [ ] OpenClaw agent usage expectations are documented.
22+
- [ ] Safety constraints are documented: local-first behavior, no hidden network
23+
calls, no implicit GitHub creation, and no autonomous merge.
24+
- [ ] `docs/release-readiness.md` matches the current command surface.
25+
1426
## 2. Changelog
1527

1628
- [ ] `CHANGELOG.md` has an `Unreleased` section.

‎docs/release-readiness.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# StackForge Release Readiness
2+
3+
This guide defines what must be true before StackForge should be presented as a
4+
reviewable V1 scaffold CLI.
5+
6+
## CLI-first architecture
7+
8+
StackForge is intentionally CLI-first.
9+
10+
- `stackforge` is the deterministic engine that lists templates, previews
11+
scaffold output, and writes repositories locally.
12+
- Humans and agents interact with the same command surface.
13+
- CrewCmd is a later wrapper, not the source of truth for generation logic.
14+
- OpenClaw agents should call the CLI only on machines where StackForge is
15+
already installed and verified.
16+
17+
That boundary keeps the core product testable without depending on orchestration
18+
state.
19+
20+
## V1 commands
21+
22+
Release readiness for V1 is anchored to a small command surface:
23+
24+
```bash
25+
stackforge --version
26+
stackforge templates
27+
stackforge init oss-cli demo --dry-run
28+
stackforge init oss-cli demo
29+
```
30+
31+
Expected behavior:
32+
33+
- `--version` returns the installed CLI version.
34+
- `templates` lists the currently supported templates.
35+
- `init ... --dry-run` prints a deterministic plan without writing files.
36+
- `init ...` writes the scaffold locally and avoids hidden network steps.
37+
38+
`launch` can remain documented as a follow-on workflow, but V1 readiness should
39+
not depend on CrewCmd-driven orchestration being complete.
40+
41+
## Command examples
42+
43+
### Inspect available templates
44+
45+
```bash
46+
pnpm dev templates
47+
```
48+
49+
### Preview a scaffold without writing files
50+
51+
```bash
52+
pnpm dev init oss-cli my-tool --dry-run
53+
```
54+
55+
### Generate a local scaffold
56+
57+
```bash
58+
pnpm dev init oss-cli my-tool
59+
```
60+
61+
### Release verification commands
62+
63+
```bash
64+
pnpm check
65+
pnpm build
66+
pnpm check:templates
67+
pnpm smoke:init
68+
```
69+
70+
## Safety model
71+
72+
StackForge should be safe by default.
73+
74+
- No hidden network calls.
75+
- No implicit GitHub repository creation.
76+
- No default LLM calls.
77+
- No autonomous merging or publishing.
78+
- File generation must stay deterministic and reviewable.
79+
- Destructive overwrite behavior must require explicit operator intent.
80+
81+
The release bar is not just "it scaffolds"; it must scaffold in a way that is
82+
predictable enough for humans and agents to trust.
83+
84+
## OpenClaw agent workflow
85+
86+
OpenClaw is an execution environment around StackForge, not a replacement for
87+
it.
88+
89+
1. Verify the node or host has the StackForge CLI installed.
90+
2. Run `stackforge templates` or a dry run first to confirm the requested path.
91+
3. Use `stackforge init ... --dry-run` in planning or review-heavy flows.
92+
4. Run `stackforge init ...` only after the target repo name and template are
93+
confirmed.
94+
5. Hand the generated repository back to the normal branch, commit, PR, and
95+
review workflow.
96+
97+
This keeps agent usage grounded in the same deterministic CLI behavior a human
98+
maintainer would use locally.
99+
100+
## CrewCmd-later boundary
101+
102+
CrewCmd support is valuable, but it is explicitly a later wrapper.
103+
104+
For V1, release-ready means:
105+
106+
- the CLI works on its own
107+
- commands are documented
108+
- safety constraints are documented
109+
- agent usage expectations are documented
110+
- verification scripts pass
111+
112+
It does **not** require:
113+
114+
- CrewCmd packaging to be complete
115+
- orchestration-specific automation to be the only entry point
116+
- StackForge to replace OpenClaw, CrewCmd, or GitHub review flows
117+
118+
## V1 release checklist
119+
120+
Use this checklist with the general release process docs before opening a V1
121+
release PR.
122+
123+
- [ ] README explains the CLI-first architecture and CrewCmd-later boundary.
124+
- [ ] README or docs include working command examples for `templates` and
125+
`init`.
126+
- [ ] V1 command surface is limited to documented, supported behavior.
127+
- [ ] Safety expectations are documented: local-first, no hidden network calls,
128+
no implicit GitHub creation, no autonomous merge.
129+
- [ ] OpenClaw agent workflow is documented for dry runs and local execution.
130+
- [ ] `pnpm check` passes.
131+
- [ ] `pnpm build` passes.
132+
- [ ] `pnpm check:templates` passes.
133+
- [ ] `pnpm smoke:init` passes.
134+
- [ ] Any deferred CrewCmd work is clearly marked as post-V1.

0 commit comments

Comments
 (0)