feat: implement auto-scaffolding for project workflow files in bare repos

2026-09-11 18:52:50 +07:00
parent 44bb4bebf1
commit 7d77408a41
9 changed files with 441 additions and 9 deletions
@@ -0,0 +1,51 @@
+# Auto-scaffold project workflow files on first use in an existing repo
+
+## Problem
+`/init` already scaffolds TODO.md / ROADMAP.md / docs/ **manually** (plus writes AGENTS.md
+via the model). But when the user runs shiro against an *existing* project that has no
+tracking files, nothing is generated automatically — the workflow policy block stays out of
+the system prompt, no nudges ever fire, and the model has no task list context.
+
+The user's ask: when the agent starts working in an existing repo that lacks
+TODO.md / ROADMAP.md / docs/, generate them (also auto-write AGENTS.md), so the workflow
+hooks in before the first turn.
+
+## Scope
+- Auto-generate TODO.md, ROADMAP.md, docs/, and AGENTS.md in an existing repo that has none
+  of them, before the first user turn.
+- Model-driven content (the `/init` prompt pattern) rather than empty templates, so the
+  files reflect the actual project.
+- Opt-out: `workflow.autoScaffold: false` disables; `workflow.enabled: false` stays the master
+  switch. Also bail if the repo already tracks anything (TODO/ROADMAP/docs or AGENTS.md) — a
+  repo that self-tracks does not need re-scaffolding.
+- Generated files are surfaced as a `notice` event so the CLI/UI can show them.
+- No overwriting: never touch an existing file.
+
+## Files touched
+- `src/scaffold.ts` — add `scaffoldMissingAuto(cwd, model)` that (a) checks git root,
+  (b) if no TODO/ROADMAP/docs/AGENTS.md exist, generates them via one model call
+  (reuse `INIT_PROMPT`-style tone, but cover all four files), writing directly.
+- `src/session.ts` — in `send()` (first turn only, `workflow.autoScaffold !== false` and
+  `workflow.enabled !== false`), call `scaffoldMissingAuto` once; if anything was written,
+  set a flag so `systemFor()`'s `workflowPolicy()` sees the files right away, bump
+  `versions.workflow`, and yield a `notice`.
+- `src/config.ts` — parse `workflow.autoScaffold` from config.
+- `src/session.ts` `SessionOptions.workflow` — add `autoScaffold?: boolean` (default true).
+- `test/scaffold.test.ts` (new or extend) — auto-scaffold on a repo with nothing; bail when
+  TODO.md exists; bail when AGENTS.md exists; opt-out flag.
+- `docs/workflow.md` — document auto-scaffold + the flag.
+
+## Verification
+- `bun run typecheck` clean.
+- `bun test` full suite green.
+- New tests cover: auto-scaffold writes 4 files in a bare repo; existing TODO.md bails;
+  existing AGENTS.md bails; `autoScaffold:false` skips; notice event emitted.
+- `bun run build` compiles.
+
+## Risks / decisions
+- One model call for all four files keeps it cheap and atomic-ish; content is project-specific.
+- Runs once per session (flag), at first `send()` *before* the model's real turn, so the
+  system prompt and the turn see it. If the model call fails, degrade to the existing
+  `scaffoldWorkflowFiles` empty-template fallback — never fail the turn.
+- Cwd-relative writes: resolve against the **git root**, not `process.cwd()` (matches
+  `workflowPolicy`). Nested-cwd runs still write at the repo root.