bcobs-spec
Skill13 starsChanged 24 days agoMITView on GitHub
Write a feature spec for BC Observatory that a parallel coding session can pick up and build without asking. Use when the owner asks to spec, design, write up or plan a feature, a fix or a change for the observatory ("spec this", "write a spec for", "the end goal is a spec", "maak een spec"), or to revise a proposed spec in docs/specs/. Covers where to work, the one scoping round, verifying every claim against the tree, reserving decision and milestone numbers without colliding with other sessions, the spec's sections, registering it in PLAN and HANDOFF, and pushing it so the coding session finds it. A spec session writes and pushes the spec only; it installs, runs and builds nothing. Also the spec-writing flow waldo.Jarvis's League runs from /sdd-draft (operator mode: no questions, no gh, no push).
- Commits and pushes
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- sdd-buildSkill
- sdd-draftSkill
- sdd-reviewSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
Never reset, check out over, or pull into a worktree that has another session's uncommitted files.
- Very specific: line 32
Read AGENTS.md, docs/PLAN.md, the tail of docs/DECISIONS.md and the specs in docs/specs/ that touch the same code before writing.
- Very specific: line 37
No installs (no uv tool install, no claude mcp add, no brew), no ssh that changes the Mac Mini, no nightly dispatch, no code edits outside …
- Very specific: line 56
Every claim about the code cites a file and line, verified against a named commit: write "verified against the tree at <short sha> on …
- Very specific: line 58
Every number is measured on the committed data/ (object counts, sizes, stars per lens), with the command or file that gave it.
- Distinctive: line 60
When the spec depends on another spec, read that spec's "built, deviations" section, not its plan.
- Very specific: line 165
Do not append to docs/DECISIONS.md: the coder does that at ship time.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing a spec for BC Observatory
The owner specs in one session while another session codes. The coding session finds work in exactly one place:
the "Open specs, not yet implemented" section of docs/HANDOFF.md on origin/main. A spec that is not
pushed, or not listed there, does not exist for the coder.
A spec has two possible builders: a manual session (from that HANDOFF list, or /sdd-build), or waldo.Jarvis's
League. The League reads docs/specs/*.md (.league.json) only through a YAML frontmatter block with --- on line 1;
a spec without issue: is invisible to it. Its go signal is the spec-approved label on the spec's GitHub issue, which
only the owner applies (the HUD's Approve button does it). Writing a spec is the same work either way; the two modes
differ only where this skill says so.
Which mode am I in? Operator mode when your task says so (the League's preamble names JARVIS_OPERATOR=1; its
Bash refuses $, so do not echo the variable there). Otherwise echo "${JARVIS_OPERATOR:-0}": 1 = operator mode.
In operator mode the League handed this session a checkout and an issue (/sdd-draft), it holds git, there is no
network credential, and sdd-draft section 0 lists the only tools you have: where it differs from this skill
(numbers by Grep, PLAN and HANDOFF edits proposed in section 12 instead of applied, no commit), sdd-draft wins.
Anything else = a manual session.
1. Where to work
- Operator mode: work in the checkout and on the branch you were given; no worktree.
- Manual session: work in a worktree no coding session uses. Run
git worktree listand ask yourself which ones are busy; when in doubt, create your own fromorigin/main:git worktree add -b spec/<slug> ../waldo.BCObservatory-spec-<slug> origin/main. - Never reset, check out over, or pull into a worktree that has another session's uncommitted files.
- Read
AGENTS.md,docs/PLAN.md, the tail ofdocs/DECISIONS.mdand the specs indocs/specs/that touch the same code before writing.
2. A spec session changes nothing else
- No installs (no
uv tool install, noclaude mcp add, no brew), no ssh that changes the Mac Mini, no nightly dispatch, no code edits outsidedocs/. "Install it on the Mini" in the request describes the spec's scope: the spec writes the install steps for the Mini (infra/mini/*.sh, gated) and the developer Mac (docs/RUNBOOK.md), and how to undo them. - Reading the tree, the committed
data/,gh apion public repos and read-only probes are fine.
3. One scoping round, then write
Operator mode: there is nobody to ask. Skip the round, take the cheapest option for each question you would have asked,
and write every open question into section 9 with the default the coder takes. When the issue is too vague to say what
to build at all, write no spec and end NEEDS-ANSWER: <one concrete question>.
Manual session: before writing, ask one AskUserQuestion round (at most four questions) for what genuinely changes the work: how
much infrastructure, whether a principle-changing phase is in or becomes its own decision, which adjacent small
tranches ride along. Recommend the cheapest option first. Keep resident servers, embeddings and new services out
unless the owner picks them. Do not ask what the repository answers.
4. Verify, then claim
- Every claim about the code cites a file and line, verified against a named commit: write
"verified against the tree at
<short sha>on<date>" in the scope paragraph. - Every number is measured on the committed
data/(object counts, sizes, stars per lens), with the command or file that gave it. A coder will check them; wrong numbers cost a round trip. - When the spec depends on another spec, read that spec's "built, deviations" section, not its plan.
- A version bump lists every place the version lives. Find them by grepping the tree for the current version
string, not from memory:
git grep -n '0\.7\.1' -- ':!package-lock.json' ':!docs/'for the MCP, the same for the plugin version, and put the full list in the task. The spec behind PR #6 listed four places and missed the fifth,.claude-plugin/marketplace.json; a coder follows the list it is given. - A release step names the repo's release mechanism and cites its decision: for the MCP, the
publish-mcpworkflow dispatch (gh workflow run publish-mcp.yml --ref main, D40). "Release it as the last one was" is not an instruction: the coder cannot look up how the last one was done and invents a command.
5. Reserve the numbers
Decision numbers (Dnn) and milestones (Mnn) have no lock and collided three times in one day. Take the next
free number across origin, your tree and every other worktree:
git fetch -q origin
{ for f in DECISIONS.md PLAN.md HANDOFF.md; do git show origin/main:docs/$f; done
git worktree list --porcelain | awk '/^worktree /{print $2"/docs"}' |
xargs -I@ find @ -maxdepth 2 -name '*.md' -exec cat {} + 2>/dev/null
} | grep -oE '\b(D[0-9]{2,3}|M[0-9]{1,2})\b' | sort -u |
awk '{t=substr($0,1,1); n=substr($0,2)+0; if (n>m[t]) m[t]=n} END {print "highest D" m["D"] ", highest M" m["M"]}'Take one above each (on 2026-10-07 the output was D73 and M11, held by the media-rows spec session, so the next spec takes D74 and M12), write them into the spec header as "reserved", and push soon (section 8): the push is what claims them.
The League only appends numbers a spec already reserved; it takes none at build time, so a League build and a manual
session in parallel cannot collide on a number unless both specs were written against the same stale view. A League
draft has no network and cannot fetch: its numbers come from the local origin/main and the worktrees it can see. In
operator mode say so in section 9 ("reserved from the tree at <sha> without a fetch; re-run the number command when
approving") and in the report. A real collision surfaces when the PR merges, as a conflict in docs/DECISIONS.md,
docs/PLAN.md or docs/HANDOFF.md: keep both entries and renumber the later spec.
6. The spec file
docs/specs/<slug>.md, kebab-case, no number in the name. Header, then numbered sections:
---
issue: <N>
status: draft
---
# <Title: what changes, in the reader's words>
Status: proposed, <YYYY-MM-DD>. Decision: Dnn (reserved, appended to `docs/DECISIONS.md` at ship time). Owner: waldo.
Scope: <what it touches>. Every claim below was verified against the tree at `<sha>` on <date>. Not in scope: <...>.The frontmatter is what the League reads: --- on line 1, issue: a number (the GitHub issue in this repository the
spec belongs to), status: read by its first word (draft, approved, implemented; bare scalars, a trailing
# comment is fine). The Status: line in the body is for people and stays in step: draft is proposed,
implemented is implemented. tests/unit/specs-frontmatter.test.ts checks both, and that every spec listed in
HANDOFF "Open specs" has the frontmatter.
Never write status: approved and never apply the spec-approved label (or any label, or create one). Approval is
the owner's act, taken after reading the spec; a spec you write is always draft, in both modes, even when the owner
says "go ahead".
The issue. Manual session: reuse the spec's issue: when you are revising a spec that has one; otherwise
gh issue list --state all --search "<title>" for an existing one, else create it just before the commit so the
number is in the file:
gh issue create --title "<spec title>" --body "<one paragraph: the problem and the change>\n\nSpec: docs/specs/<slug>.md (<blob url on main>), Dnn, Mnn."
and take the number from the URL it prints. No --label. Operator mode: no gh; issue: is the number /sdd-draft
was given.
- Goal: the problem with evidence (file:line, measured numbers), then "After this change:" bullets.
- Reader- and agent-facing behaviour, after: pages, markdown, MCP, the site; exact wording where it matters.
- Decisions: the draft Dnn text, and what was rejected with the reason for each.
- Contract: functions, files, schemas, config keys, data shapes, one example record.
- Test plan (write first): unit tests with their inputs and expected outputs.
- Tasks: in order, grouped in phases that can ship alone; say which phase rewrites many pages (one large content commit) and why.
- Verification: the exact commands and checks, including the site build and any real-data check.
- Later, not in this spec.
- Risks and open questions: with the default the coder takes when nobody answers.
- Files: new and changed.
- Definition of Done: checkable, including the DECISIONS, PLAN and HANDOFF edits, and the spec's own: section
12 "Built, deviations" and
status: implemented. Whoever ticks it (the builder or the PR's review, below) must be able to tell pass from fail without asking. End it with this item, Dnn and Mnn filled in:- [ ] Dnn appended to docs/DECISIONS.md; PLAN Mnn marked shipped; HANDOFF entry moved from "Open specs" to "Where things stand"; section 12 "Built, deviations" inserted (this section kept as 13, marked applied) and status implemented in the frontmatter and the body. A League build leaves the spec alone and writes section 12 and the status lines into docs/built/<slug>.md; the PR's review moves them in (sdd-build section 4, sdd-review section 6). - Proposed edits to other files (not applied): the Dnn text, the PLAN row, the HANDOFF entry, anything for
AGENTS.mdorCONTENT-NOTICE.md. The coder applies them at ship time (/sdd-build). The spec's own edits ("12. Built, deviations" inserted before this section, which stays as section 13 marked applied, the ticked Definition of Done and the status flip) are the builder's in a manual build. In a League build they are the PR review's: the League quarantines a build that edits its own spec (waldo.Jarvis spec 696, amendment N1), so its builder hands them over indocs/built/<slug>.mdand/sdd-reviewapplies them before merge.
Repository rules a spec must respect, never relax: the pipeline is deterministic first, LLM last and only on deltas
(pipeline/lib/llm.ts, roles in config/models.json, no API key); generated content/ and data/ are never
hand-edited (data/overrides/*.yaml); community text stays derived (CONTENT-NOTICE.md); stable ids, never title
matching; secrets only on the Mini.
7. Register it
Operator mode: do not edit PLAN or HANDOFF; put the row and the entry below into section 12 (sdd-draft section 1).
docs/PLAN.mdsection 5: a milestone row| **Mnn <short name>** | <deliverables> (\docs/specs/<slug>.md`, Dnn, proposed) |<effort>|<token risk>|, before thev0.2+` row.docs/HANDOFF.md, section "Open specs, not yet implemented": one entry with the spec path, decision, milestone,Status: proposed <date>, nothing implemented, the issue asissue #N, where to start (the first task), and what readers see until it lands.- Do not append to
docs/DECISIONS.md: the coder does that at ship time.
8. Commit and push
Operator mode: do not commit and do not push; the League commits your spec, pushes it and opens the PR. The rest of this section is the manual session's.
Stage by name, never git add -A. Commit only the spec, PLAN and HANDOFF:
git add docs/specs/<slug>.md docs/PLAN.md docs/HANDOFF.md
git commit -m "docs: spec for <title> (Dnn, Mnn)"
if git pull --rebase origin main; then git push origin HEAD:main; else echo "rebase conflict: resolve, do not push"; fiA live nightly on the Mini rebases its checkpoints over a docs push and retries until its push lands (D58, and
pushWithRetry since run 37664505302 aborted on two docs pushes racing a four-minute rebase), so pushing during a run
is safe. Still prefer not to push in the last minutes of a run (gh run list --workflow nightly --limit 1): the final
commit carries every rewritten page. If the
rebase conflicts in docs/HANDOFF.md or docs/PLAN.md, keep both sides' entries; renumber yours if another session
took the same Dnn or Mnn, and say so in the commit.
9. Hand-off
Manual session: end with a short message to the owner: the spec path, the issue number (and that you created it), Dnn
and Mnn, the phases, what each costs (pages rewritten, nightly time, installs), and the open questions with their
defaults. Add the two ways on: "build it by hand with /sdd-build docs/specs/<slug>.md, or apply the spec-approved
label to issue #N to hand it to the League (it stays draft until you do)". A manual session starts from the HANDOFF
entry; it needs nothing else from this session.
Operator mode: end with the report the operator handed you: outcome, the spec path, Dnn and Mnn as reserved, the open questions, and that nothing was approved.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

