agentleFS
waldo1001waldo1001/waldo.BCObservatory/.claude/skills/bcobs-spec/SKILL.md

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

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
  1. Distinctive:

    Never reset, check out over, or pull into a worktree that has another session's uncommitted files.

    line 31
  2. Very specific:

    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.

    line 32
  3. Very specific:

    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 …

    line 37
  4. Very specific:

    Every claim about the code cites a file and line, verified against a named commit: write "verified against the tree at <short sha> on …

    line 56
  5. Very specific:

    Every number is measured on the committed data/ (object counts, sizes, stars per lens), with the command or file that gave it.

    line 58
  6. Distinctive:

    When the spec depends on another spec, read that spec's "built, deviations" section, not its plan.

    line 60
  7. Very specific:

    Do not append to docs/DECISIONS.md: the coder does that at ship time.

    line 165

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 list and ask yourself which ones are busy; when in doubt, create your own from origin/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 of docs/DECISIONS.md and the specs in docs/specs/ that touch the same code before writing.

2. A spec session changes nothing else

  • 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 docs/. "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 api on 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-mcp workflow 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.

  1. Goal: the problem with evidence (file:line, measured numbers), then "After this change:" bullets.
  2. Reader- and agent-facing behaviour, after: pages, markdown, MCP, the site; exact wording where it matters.
  3. Decisions: the draft Dnn text, and what was rejected with the reason for each.
  4. Contract: functions, files, schemas, config keys, data shapes, one example record.
  5. Test plan (write first): unit tests with their inputs and expected outputs.
  6. Tasks: in order, grouped in phases that can ship alone; say which phase rewrites many pages (one large content commit) and why.
  7. Verification: the exact commands and checks, including the site build and any real-data check.
  8. Later, not in this spec.
  9. Risks and open questions: with the default the coder takes when nobody answers.
  10. Files: new and changed.
  11. 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).
  12. Proposed edits to other files (not applied): the Dnn text, the PLAN row, the HANDOFF entry, anything for AGENTS.md or CONTENT-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 in docs/built/<slug>.md and /sdd-review applies 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.md section 5: a milestone row | **Mnn <short name>** | <deliverables> (\docs/specs/<slug>.md`, Dnn, proposed) | <effort> | <token risk> |, before the v0.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 as issue #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"; fi

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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.