laurence/itelescope
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Bootstrap: Default Workflow scaffold

Browse source 
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).
This commit is contained in:
Laurence 2026-07-17 14:20:36 +01:00
commit 3fad877dee
7 changed files with 350 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

6
.gitignore vendored Normal file
View file

@ -0,0 +1,6 @@
# local scratch and secrets
*.token
*.key
scratch/
Thumbs.db
.DS_Store

51
CLAUDE.md Normal file
View file

@ -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

54
docs/documentation-policy.md Normal file
View file

@ -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.

63
docs/project-setup.md Normal file
View file

@ -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

58
docs/user-expectations.md Normal file
View file

@ -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).

76
docs/workflow.md Normal file
View file

@ -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
```

42
state/PROJECT.md Normal file
View file

@ -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