Bootstrap: Default Workflow scaffold

Repo created for a reference/review of the iTelescope.net remote telescope
network. This commit copies the Default Workflow in (CLAUDE.md and docs/ from
the Default-Workflow repo), adds a .gitignore (secrets and scratch), and fills
in state/PROJECT.md with the objective: review every telescope on the network
and provide a choosing guide, using only public sources (support article and
the maintained Google Sheet; the go.itelescope.net launchpad is login-only).

docs/documentation-policy.md

@@ -0,0 +1,54 @@
+# Documentation policy
+
+Two separate ideas, both about making the repo the single source of truth so that no
+session ever depends on another session's chat history.
+
+## A. State lives in committed markdown, not in the chat
+
+Do not use chat history, context, or cache as memory. They cost tokens to carry and
+vanish between sessions. Instead, everything a future session needs is written to the
+`state/` directory and committed:
+
+| File | Holds |
+|------|-------|
+| `PROJECT.md` | Objectives, scope, description, audience. The anchor. |
+| `ARCHITECTURE.md` | How the system is built and why it is built that way. |
+| `DECISIONS.md` | A dated log of decisions and their rationale. Append, never rewrite history. |
+| `TODO.md` | Done / in progress / pending. The current state of play. |
+| `NOTES.md` | Working notes, gotchas, environment quirks, dead ends to avoid. |
+
+Update these as part of the work, not as an afterthought. A change to how the system
+works is not finished until `ARCHITECTURE.md` or `DECISIONS.md` reflects it.
+
+Templates for all of these are in `templates/`.
+
+## B. Documentation is written in a separate session from the code
+
+The user facing documentation (README, guides, API docs, changelog) is **not** written
+in the same session that writes the code. This is deliberate:
+
+- It forces the building session to leave a complete trail. If the code cannot be
+  documented later from git history and comments alone, the trail was not good enough.
+- It keeps each session cheap and focused. A building session spends its budget
+  building; a documentation session spends its budget writing docs.
+- It gives the docs a cold, independent reader who documents what the code actually
+  says, not what the author remembers intending.
+
+### What the building session must leave behind
+
+So the later documentation session can work with no chat history:
+
+1. **Commit messages with full notes** - what changed, why, and any trade-offs. See
+   [Workflow](workflow.md).
+2. **A complete PR description** - feature, tools used, what was achieved, how it works.
+3. **Code comments that explain intent** - not what a line does (the code shows that)
+   but why it exists, what it assumes, and what would break it. Comment for a stranger
+   who was not in the room.
+4. **Current `state/` files** - especially `ARCHITECTURE.md` and `DECISIONS.md`.
+
+### What the documentation session does
+
+Starts cold. Reads `git log`, the PRs, the code and its comments, and the `state/`
+files. Writes the documentation from those alone. If something cannot be understood
+from the repo, that is a gap to flag, not a reason to guess or to reach for lost chat
+context.

docs/project-setup.md

@@ -0,0 +1,63 @@
+# Project setup
+
+How to start a new project on the Default Workflow. Do this once, at the beginning of
+a project, before any feature work.
+
+## 1. Create the repository
+
+- Create an empty repo on the forge (git.discworld.casa or wherever the project lives).
+- Clone it, or `git init` locally and add the remote.
+- The trunk branch is `main` unless the forge defaults to `master`; either is fine, be
+  consistent and refer to it as "the trunk" in docs.
+
+## 2. Copy the workflow files in
+
+From this Default-Workflow repo, copy into the new project root:
+
+- `CLAUDE.md` - so every session loads the workflow automatically.
+- `docs/` - the detailed workflow docs (or link to them if you prefer one source of
+  truth; copying keeps the project self contained and offline readable).
+- `templates/*` into `state/` (see next step).
+
+## 3. Create the state directory
+
+The `state/` directory is the project's memory. It replaces chat history. Copy the
+templates and fill in the project specifics:
+
+```
+state/
+  PROJECT.md      - objectives, scope, description, who it is for
+  ARCHITECTURE.md - how the system is built and why
+  DECISIONS.md    - dated log of decisions and their rationale
+  TODO.md         - what is done, in progress, and pending
+  NOTES.md        - working notes, gotchas, environment quirks
+```
+
+Fill in `PROJECT.md` first. It anchors every later session. A session that reads only
+`PROJECT.md`, `TODO.md` and `DECISIONS.md` should understand what the project is and
+what to do next.
+
+## 4. Add a .gitignore
+
+Ignore build artefacts, dependencies, secrets and local scratch. Never commit tokens
+or credentials.
+
+## 5. First commit
+
+Commit the scaffold to the trunk directly (this is bootstrap, not a feature):
+
+```
+git add .
+git commit
+```
+
+Write a full commit message describing what the scaffold contains and why. From here
+on, all work follows the [Workflow](workflow.md): a branch per feature.
+
+## Checklist
+
+- [ ] Repo created and remote set
+- [ ] `CLAUDE.md` and `docs/` present in project root
+- [ ] `state/` created from templates, `PROJECT.md` filled in
+- [ ] `.gitignore` in place, no secrets tracked
+- [ ] Scaffold committed to the trunk

docs/user-expectations.md

@@ -0,0 +1,58 @@
+# User expectations
+
+How the user expects a Claude Code session to behave under this workflow. Read this
+once per session; it rarely changes.
+
+## Work autonomously
+
+Do not stop to ask which task to pick up next, or for confirmation before routine work.
+Default sensibly and keep shipping. Read `state/TODO.md`, choose the next sensible
+item, do it. Only ask when a decision is genuinely the user's to make and cannot be
+resolved from the repo or sensible defaults.
+
+## Cost before speed
+
+Staying within usage limits is more important than finishing fast or gold plating.
+When in doubt, take the cheaper path. See [Cost and tokens](cost-and-tokens.md).
+
+## Subagents are allowed
+
+Spawning subagents, parallel agents, background tasks and multi-agent workflows is a
+normal, permitted part of the workflow. Using them is not a breach of the cost rule
+when they are the effective path: fan-out searches that keep bulk file contents out of
+the main context, independent pieces of work run in parallel, or verification passes
+over completed work.
+
+The cost rule still applies to each one. A subagent must earn its keep: do not spawn
+one for work a single cheap tool call can do, and do not fan out speculatively. Record
+subagent use in the PR under "Tools used" so the cost trail stays honest.
+
+## Leave a clean trail
+
+Every feature ends as: a merged branch, full commit notes, a complete PR, current
+`state/` files, and code commented well enough to document later. The user should be
+able to open the repo weeks later, with no memory of the session, and understand what
+happened and why from the repo alone.
+
+## Report honestly
+
+If tests fail, say so with the output. If a step was skipped, say that. If something is
+done and verified, say so plainly without hedging. Do not claim more than was done.
+
+## Writing style
+
+- No em dashes in prose. Use commas, full stops, or restructure.
+- British spelling in prose and copy. Preserve code identifiers as written.
+- Plain, direct language. Say what happened.
+
+## Confirm before the hard to reverse
+
+Routine coding is autonomous. But confirm first for actions that are hard to undo or
+that reach outside the repo: force pushes, history rewrites, deleting things you did
+not create, deploying, or sending data to external services. Approval for one such
+action does not carry to the next.
+
+## The building session stops at merge
+
+Do not write the user facing documentation in the building session. That is a separate
+session's job. See [Documentation policy](documentation-policy.md).

docs/workflow.md

@@ -0,0 +1,76 @@
+# Workflow
+
+The branch, commit, PR and merge process for every feature. A "feature" is any unit of
+change: a new capability, a fix, a refactor.
+
+## 1. Branch per feature
+
+Never build directly on the trunk. Start each feature from an up to date trunk:
+
+```
+git checkout main
+git pull
+git checkout -b feature/<short-kebab-description>
+```
+
+Use a clear prefix: `feature/`, `fix/`, `refactor/`, `docs/`.
+
+## 2. Commit with full notes
+
+Commit in logical steps, not one giant dump at the end. Every commit message carries
+the full record of what changed and why, because the commit history is the primary
+source a later documentation session reads.
+
+Message shape:
+
+```
+<type>: <concise summary in the imperative>
+
+What changed:
+- <file or area>: <what and why>
+- ...
+
+Why:
+- <the reasoning, constraints, or decision behind the change>
+
+Notes:
+- <anything a cold session should know: trade-offs, follow-ups, gotchas>
+```
+
+Do not write "written by Claude" in code or messages. If the project convention
+requires an authorship tag (for example `ai:claude`), follow that project's rule.
+
+## 3. Keep state files current
+
+As you work, update `state/TODO.md` and `state/DECISIONS.md`. Decisions go in the log
+with a date and rationale. This is what lets the next session skip the chat history.
+
+## 4. Open a PR when the feature is complete
+
+When the feature is done and self consistent, push the branch and open a PR. The PR
+description is the human and machine readable summary of the feature. Use the template
+in `templates/PR_TEMPLATE.md`. It must state:
+
+- **Feature** - what was built, in plain terms.
+- **What was achieved** - the outcome, and how to verify it.
+- **Tools used** - languages, libraries, commands, services involved.
+- **How it works** - enough for a documentation session to start from the PR alone.
+- **Follow ups** - anything deferred.
+
+## 5. Merge into the trunk
+
+Merge the PR into the trunk once it is complete. Prefer a merge that preserves the
+commit history (the notes in each commit are valuable). Delete the feature branch after
+merge.
+
+## 6. Do not document in this session
+
+Writing the user facing documentation is a separate job, done in a separate session,
+against the merged history. See [Documentation policy](documentation-policy.md). Your
+job in the building session ends at a merged, well commented, well described feature.
+
+## Summary
+
+```
+branch  ->  commit (full notes)  ->  update state/  ->  PR (feature, tools, outcome)  ->  merge  ->  stop
+```