From 3fad877deef6c4237c609b9fcd1197694824c6a7 Mon Sep 17 00:00:00 2001 From: Laurence Date: Fri, 17 Jul 2026 14:20:36 +0100 Subject: [PATCH] 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). --- .gitignore | 6 +++ CLAUDE.md | 51 ++++++++++++++++++++++++ docs/documentation-policy.md | 54 +++++++++++++++++++++++++ docs/project-setup.md | 63 ++++++++++++++++++++++++++++++ docs/user-expectations.md | 58 +++++++++++++++++++++++++++ docs/workflow.md | 76 ++++++++++++++++++++++++++++++++++++ state/PROJECT.md | 42 ++++++++++++++++++++ 7 files changed, 350 insertions(+) create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 docs/documentation-policy.md create mode 100644 docs/project-setup.md create mode 100644 docs/user-expectations.md create mode 100644 docs/workflow.md create mode 100644 state/PROJECT.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d7d1347 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +# local scratch and secrets +*.token +*.key +scratch/ +Thumbs.db +.DS_Store diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6a35dc1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,51 @@ +# Default Workflow + +This file is the entry point for any Claude Code session working under the Default +Workflow. Keep it small and read the detailed docs on demand so a session does not +load everything at once (see [Cost and tokens](docs/cost-and-tokens.md)). + +## What this is + +A standard operating procedure for building software with Claude Code. It defines how +a project is set up, how features are branched, committed, reviewed and merged, how +documentation is produced, and what the user expects. Copy this workflow into a new +project (see [Project setup](docs/project-setup.md)) and follow it. + +## The five rules + +1. **Minimise cost.** Staying within usage limits matters more than speed. Prefer + cheap actions over expensive ones. Read only what you need. Subagents and parallel + processing are allowed when they are the effective path (see + [User expectations](docs/user-expectations.md)). See + [Cost and tokens](docs/cost-and-tokens.md). + +2. **State lives in the repo, not the chat.** Do not rely on chat history, context, or + cache to remember decisions, todos, notes, architecture, or objectives. Write them + to the committed markdown files under `state/` so a fresh session can pick up with + no prior context. See [Documentation policy](docs/documentation-policy.md). + +3. **Every feature is a branch.** Create a branch, commit with full notes in each + message, open a PR describing the feature, the tools used and what was achieved, + then merge into the trunk. See [Workflow](docs/workflow.md). + +4. **Code and its documentation are written in separate sessions.** The building + session comments the code well enough that a later, cold session can write the docs + from git history and comments alone. See [Documentation policy](docs/documentation-policy.md). + +5. **Comment for a stranger.** Assume the next session has no memory of why you did + anything. The commit history and code comments are the only record. + +## Start of every session + +1. Read `state/PROJECT.md`, `state/TODO.md` and `state/DECISIONS.md` (cheap, small). +2. Check `git log --oneline -15` and `git status` to see where things stand. +3. Do the work under the rules above. +4. Before ending, update the `state/` files so the next session needs no chat history. + +## Detailed docs + +- [Project setup](docs/project-setup.md) - starting a new project on this workflow +- [Workflow](docs/workflow.md) - branch, commit, PR and merge process +- [Cost and tokens](docs/cost-and-tokens.md) - keeping usage within limits +- [Documentation policy](docs/documentation-policy.md) - comments, and docs in a separate session +- [User expectations](docs/user-expectations.md) - how the user wants Claude to behave diff --git a/docs/documentation-policy.md b/docs/documentation-policy.md new file mode 100644 index 0000000..287c0d8 --- /dev/null +++ b/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. diff --git a/docs/project-setup.md b/docs/project-setup.md new file mode 100644 index 0000000..d5abcf9 --- /dev/null +++ b/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 diff --git a/docs/user-expectations.md b/docs/user-expectations.md new file mode 100644 index 0000000..ea17fe5 --- /dev/null +++ b/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). diff --git a/docs/workflow.md b/docs/workflow.md new file mode 100644 index 0000000..c4b288a --- /dev/null +++ b/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/ +``` + +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: + +``` +: + +What changed: +- : +- ... + +Why: +- + +Notes: +- +``` + +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 +``` diff --git a/state/PROJECT.md b/state/PROJECT.md new file mode 100644 index 0000000..9139d4e --- /dev/null +++ b/state/PROJECT.md @@ -0,0 +1,42 @@ +# Project: itelescope + +> The anchor document. A session that reads only this, TODO.md and DECISIONS.md should +> understand what the project is and what to do next. Keep it current. + +## Objective + +A reference and review of the iTelescope.net remote telescope network: what each +telescope is, what it is good at, and which one to book for a given kind of target. + +## Scope + +- In scope: reviews and spec tables for every telescope on the iTelescope network, + grouped by observatory; source data snapshots; guidance on choosing a scope. +- Out of scope: automating bookings, image processing, anything requiring the + iTelescope login (the launchpad at go.itelescope.net is authenticated). + +## Audience + +Laurence, when planning imaging or photometry runs on iTelescope, and anyone else +choosing a telescope on the network. + +## Description + +iTelescope.net operates remote telescopes across six observatories (Utah, Sierra +California, Siding Spring Australia, Deep Sky Chile, AstroCamp Spain, e-EyE Spain). +Public specs are scattered across a Freshdesk support article and a maintained Google +Sheet. This repo snapshots that data and turns it into a usable review: per-telescope +assessments plus a "which scope for what" guide. + +## Success criteria + +- Every active telescope on the network has an entry with specs and an assessment. +- A reader can pick the right scope for widefield, deep space, galaxies, photometry, + or free imaging without visiting the source pages. + +## Key facts + +- Trunk branch: main +- Forge / remote: https://git.discworld.casa/laurence/itelescope +- Runtime / stack: markdown only; source data in data/ as CSV +- How to run it: nothing to run; read TELESCOPES.md