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

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