File Structure

Complete reference of the Scraut repository layout and every significant file.

Top-level structure

scraut/
├── .github/
│   └── workflows/          ← All GitHub Actions automation
├── apps/
│   ├── automation/         ← Python automation layer
│   ├── create-scraut/      ← npm setup wizard (npx create-scraut)
│   ├── docusaurus/         ← Documentation source (this site)
│   ├── github-app/         ← GitHub App webhook handler (optional)
│   └── portal/             ← Visibility portal web app
├── docs/                   ← Built documentation (GitHub Pages output)
├── workspace/              ← Human-editable source of truth
├── .scraut/                ← Bot-generated output (never edit manually)
└── CLAUDE.md               ← Architecture rules for AI assistants

`workspace/` — Human source of truth

Everything under workspace/ is written by humans. Scraut automation never overwrites these files.

workspace/
├── scraut.yml                          ← Team configuration (primary config file)
│
├── sprint/
│   └── NN/                            ← One directory per sprint (01, 02, 03...)
│       ├── meta.md                    ← Sprint goal, issues, capacity
│       ├── standup/
│       │   └── YYYY-MM-DD/
│       │       ├── alice.md           ← Alice's daily standup
│       │       ├── bob.md             ← Bob's daily standup
│       │       ├── agent-backend.md  ← Agent standup (if agent mode on)
│       │       └── _example.md       ← Format reference (never processed)
│       ├── retrospective/
│       │   ├── alice.md              ← Alice's retro input
│       │   ├── bob.md
│       │   └── _example.md          ← Format reference (never processed)
│       ├── grooming/
│       │   ├── backlog-ideas.md      ← Anyone can append new ideas here
│       │   └── _example.md          ← Format reference (never processed)
│       ├── decisions/
│       │   └── _example.md          ← Format reference (never processed)
│       └── adr/
│           └── _example.md          ← Format reference (never processed)
│
├── team/
│   ├── capacity.md                   ← OOO and availability per sprint
│   └── _example.md                  ← Format reference (never processed)
│
├── okr/
│   ├── okr.md                        ← Team objectives and key results
│   └── _example.md                  ← Format reference (never processed)
│
├── customer/
│   ├── feedback.md                   ← Customer feedback log
│   └── _example.md                  ← Format reference (never processed)
│
├── knowledge/
│   └── _example.md                  ← Format reference (never processed)
│
└── milestones/
    ├── _example-milestone.md         ← Format reference (never processed)
    └── v1.0/
        └── milestone.md             ← One subdirectory + milestone.md per milestone

`.scraut/` — Bot-generated output

Everything under .scraut/ is generated by GitHub Actions. Do not edit these files manually — they will be overwritten. All bot-generated files start with .

.scraut/
├── sprint/
│   └── NN/
│       ├── standup/
│       │   └── summary/
│       │       └── YYYY-MM-DD.md     ← Daily LLM-generated summary
│       ├── review/
│       │   ├── review.md             ← Sprint review document
│       │   └── retro-synthesis.md    ← Retrospective synthesis
│       ├── code/
│       │   └── YYYY-MM-DD/
│       │       └── [repo-name].md    ← Synced code activity
│       └── incidents/
│           └── [incident-name]/
│               ├── incident.md       ← Incident report (human writes)
│               └── action-items.md   ← Action items (human writes, bot reads)
│
├── insights/                         ← Cross-sprint insight reports
│
├── milestones/
│   └── [milestone-name]/
│       └── health/
│           └── forecast.md           ← Milestone health forecast
│
└── suggestions/
    ├── active/
    │   └── s001-[slug].md            ← New suggestions awaiting SM review
    ├── implemented/
    │   └── s001-[slug].md            ← Suggestions being measured
    └── resolved/
        └── s001-[slug].md            ← Measured outcomes

`apps/automation/` — Python automation layer

apps/automation/
├── requirements.txt                  ← Python dependencies
├── pyproject.toml                    ← Project config (pytest, coverage)
├── scraut/                           ← Main Python package
│   ├── cli/
│   │   └── cli.py                   ← `scraut` CLI commands
│   ├── platform/
│   │   ├── github/
│   │   │   ├── api.py               ← GitHub API client
│   │   │   └── projects.py          ← GitHub Projects API
│   │   ├── llm/
│   │   │   └── client.py            ← LLM router (Anthropic/OpenAI/Gemini/Ollama)
│   │   ├── notifications/
│   │   │   ├── slack_post.py        ← Slack webhook + bot DM
│   │   │   ├── morning_dm.py        ← Morning standup notification
│   │   │   └── weekly_digest.py     ← Weekly email/Slack digest
│   │   ├── setup/
│   │   │   └── create_labels.py     ← GitHub label creation
│   │   └── utils/
│   │       ├── config.py            ← scraut.yml loader and helpers
│   │       ├── file_utils.py        ← atomic_write, create_if_not_exists
│   │       └── date_utils.py        ← Sprint date calculations
│   └── scrum/
│       ├── standup/
│       │   ├── reset_templates.py   ← Daily standup template creator
│       │   └── generate_summary.py  ← LLM standup summariser
│       ├── sprint/
│       │   ├── create_sprint.py     ← Sprint folder + milestone creation
│       │   ├── plan_sprint.py       ← LLM sprint planning
│       │   ├── close_sprint.py      ← Sprint close + counter increment
│       │   ├── synthesise_retrospective.py ← LLM retro synthesis
│       │   └── calculate_velocity.py       ← Velocity calculation
│       ├── backlog/
│       │   ├── prioritize_backlog.py ← LLM backlog prioritisation
│       │   ├── triage_issue.py      ← LLM issue triage
│       │   └── tally_estimation.py  ← Story point emoji tally
│       ├── milestone/
│       │   ├── planning_session.py  ← LLM milestone decomposition
│       │   └── health_check.py      ← Milestone health forecasting
│       ├── visibility/
│       │   ├── derive_state.py      ← Text-file → board state derivation
│       │   └── sync_board.py        ← GitHub Projects board sync
│       ├── repo_sync/
│       │   └── prefill_standups.py  ← Code activity fetch
│       ├── suggestions/
│       │   ├── detectors.py         ← Pattern detection (deterministic)
│       │   └── measure.py           ← Suggestion impact measurement
│       └── agents/
│           ├── orchestrate.py       ← Agent dispatch logic
│           └── standup.py           ← Agent standup generation
└── test/
    ├── unit/                        ← Unit tests (no real API calls)
    │   ├── test_cli.py
    │   ├── test_imports.py
    │   ├── test_llm_client.py
    │   └── test_workflow_inline.py
    └── integration/
        └── test_workflow_coverage.py ← Tests every script's --help

`.github/workflows/` — Automation

See Workflows Reference for full descriptions.

.github/workflows/
├── daily-standup.yml
├── sprint-planning.yml
├── sprint-review.yml
├── sprint-retrospective.yml
├── backlog-grooming.yml
├── issue-triage.yml
├── estimation-tally.yml
├── pr-linker.yml
├── pr-close-stories.yml
├── dod-check.yml
├── sprint-plan-pr.yml
├── visibility-engine.yml
├── portal-publish.yml
├── milestone-planning.yml
├── milestone-respond.yml
├── morning-notification.yml
├── template-reset.yml
├── weekly-digest.yml
├── repo-sync.yml
├── incident-to-backlog.yml
├── generate-insights-workflow.yml
├── suggestion-detect.yml
├── suggestion-measure.yml
├── agent-orchestrator.yml
├── agent-backend.yml
├── agent-frontend.yml
├── agent-test.yml
├── agent-review.yml
└── test-ci.yml

File formats

For the full content format of every file in workspace/ (with annotated examples), see the Workspace File Formats reference →

File naming conventions

Pattern	Meaning
`workspace/sprint/NN/standup/DATE/login.md`	NN is zero-padded (01, 02...)
`.scraut/suggestions/active/s001-slug.md`	Sequential suggestion number
`.scraut/sprint/NN/code/DATE/repo-name.md`	repo-name is the `name` field from `repos:` config
`<!-- BOT-GENERATED -->`	First line of every `.scraut/` file

Rules Scraut enforces

Rule	Implementation
Never overwrite human files	All human-zone writes use `create_if_not_exists()`
Bot commits have `[skip ci]`	All workflow git commits include `[skip ci]` in message
One file per contributor	`workspace/sprint/NN/standup/DATE/login.md` — one per login
Board is derived view	`sync_board.py` reads text files; never reads the board
`_*.md` files are always skipped	`glob_md()` in `file_utils.py` filters out any file whose name starts with `_`

Top-level structure​

workspace/ — Human source of truth​

.scraut/ — Bot-generated output​

apps/automation/ — Python automation layer​

.github/workflows/ — Automation​

File naming conventions​

Rules Scraut enforces​