shiro-neko/docs/workflow.md

# Project-driven agent workflow

Shiro Neko treats a repository the way this project treats itself: progress
tracked in TODO.md and ROADMAP.md, docs-driven development, spec-first plans,
complete unit tests, and verify-before-done. When the repo keeps those files,
the agent's system prompt carries a short workflow policy and the session
tracks whether the workflow is being followed.

## What the agent sees

When the session starts in a git repo that has any of:

- `TODO.md` at the git root
- `ROADMAP.md` at the git root
- a `docs/` directory (configurable with `workflow.docsDir`)

the system prompt gains a "Project workflow" block:

- read TODO.md (the task list) before starting and keep it current as you go
- keep ROADMAP.md current when a milestone ships
- write a short plan first (spec-first) for anything non-trivial
- add tests alongside code; the project expects complete unit tests
- verify with the project's check commands (tests/typecheck/build) before
  declaring done

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
existing `AGENTS.md` / `CLAUDE.md` / `.shiro.md` loading: outermost first, git
root down to cwd.

## The nudge

After a turn that wrote files (edit_file, write_file, apply_patch, ...) but
never called `todo_write`, the session emits one soft notice:

```
reminder: you modified files without updating the project task list (TODO.md).
Keep it current: mark what you did.
```

Design constraints:

- **Once per session.** Repeating a nag trains the model to ignore it.
- **Not a gate.** The agent stays in control; this is guidance, not a block.
- **Only when the repo has a TODO/ROADMAP.** A repo that tracks nothing gets
  no reminder.
- Suppressed when the turn already called `todo_write` — the task list is
  current, nothing to say.

## Configuration

```yaml
workflow:
  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

`/workflow` renders a panel with the project's tracking state and the
session's behaviour:

| row | meaning |
|---|---|
| `workflow` | on/off from config |
| `TODO.md` | present? line count |
| `ROADMAP.md` | present? line count |
| `docs dir` | present? file count (bounded at 200) |
| `reminders sent` | whether this session nudged (once, ever) |

## Relationship to AGENTS.md

AGENTS.md-style files are standing orders from the user and override the
agent's defaults. The workflow policy is a default that documents what a
repo tracking its own progress expects. When the two conflict, AGENTS.md
wins — the workflow feature is a floor, not a ceiling.