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

docs/configuration.md

@@ -47,7 +47,7 @@ Written by `/provider`, editable by hand. Every field is optional.
 | `maxRetries` | retries per model call for transient failures. Default 3 |
 | `maxSpendUsd` | session spend ceiling: warn at 80%, refuse the next turn at 100%. Headless exits non-zero naming the ceiling. Only enforced on priced models |
 | `maxSpendPerTurn` | per-turn spend ceiling: a single turn past this line is stopped at a step boundary, even when the session ceiling is far away. Only enforced on priced models |
-| `workflow` | project-driven workflow: `{ "enabled": true, "docsDir": "docs" }`. When the repo has TODO.md/ROADMAP.md/docs, the agent's prompt carries a workflow policy and the session nudges once when files change without the task list being updated. See [docs/workflow.md](workflow.md) |
+| `workflow` | project-driven workflow: `{ "enabled": true, "docsDir": "docs", "autoScaffold": true }`. When the repo has TODO.md/ROADMAP.md/docs, the agent's prompt carries a workflow policy and the session nudges once when files change without the task list being updated. When the repo has none, the first turn auto-scaffolds them (model-generated, never overwriting). See [docs/workflow.md](workflow.md) |
 | `subagentModel` | model id for `explore` subagents, which search rather than reason. Omit to share the parent's model. `/cost` reports subagent spend separately |
 | `plugins` | which builtin plugins to enable. Omit for `["guard", "secrets", "protect", "time", "no-force-push", "no-net-pipe", "no-root", "no-env-write"]` |
 | `toolSets` | optional tool sets beyond `core`: `edit-plus`, `nav`, `extra`, `git`, and `net`. Omit for the defaults; `net` is opt-in. See [tools](tools.md) |

docs/workflow.md

@@ -27,6 +27,31 @@ Bare repos (no TODO, ROADMAP, or docs) get no such block — the policy only
 renders when the project itself tracks progress, so a throwaway directory does
 not collect noise.
 
+## Auto-scaffolding
+
+When you run shiro against an *existing* repo that has none of the tracking
+files (no TODO.md, no ROADMAP.md, no `docs/`, no AGENTS.md), the first turn
+bootstraps them automatically: the agent investigates the repo and writes
+project-specific TODO.md, ROADMAP.md, `docs/README.md`, and AGENTS.md before
+answering. A notice reports what was written:
+
+```
+scaffolded project workflow files: TODO.md, ROADMAP.md, docs/, AGENTS.md
+```
+
+- **Never overwrites.** Any existing tracker (TODO.md, ROADMAP.md, `docs/`, or
+  AGENTS.md) at the git root means the repo already tracks itself — nothing is
+  created or touched.
+- **Model-driven content.** The files use real project content (commands,
+  layout, conventions verified against the code) like `/init` does for
+  AGENTS.md. If the model call fails, it degrades to the empty-template
+  scaffold so the turn is never interrupted.
+- **Write at the git root**, not the cwd — matches where the policy looks.
+- Runs **once per session**, before the first real turn, so the policy and the
+  first nudge already see the files.
+- The manual `/init` command still exists for when you want to write AGENTS.md
+  (and scaffold the trackers) on demand.
+
 TODO.md and ROADMAP.md are also loaded into the conversation like instruction
 files (`Project tracker (...)`), capped tighter than AGENTS.md so the agent
 sees the shape of the work without filling its context. This mirrors the
@@ -56,11 +81,14 @@ Design constraints:
 
 ```yaml
 workflow:
-  enabled: true   # master switch; default true
-  docsDir: docs   # where the project keeps developer docs; default 'docs'
+  enabled: true        # master switch; default true
+  docsDir: docs        # where the project keeps developer docs; default 'docs'
+  autoScaffold: true   # write TODO/ROADMAP/docs/AGENTS.md in a bare repo on first turn; default true
 ```
 
 `workflow.enabled: false` disables both the prompt policy and the nudge.
+`workflow.autoScaffold: false` disables only the auto-bootstrap (the policy and
+nudge still engage when the repo already tracks progress).
 
 ## /workflow