spritegen-cli 0.1.0__tar.gz → 0.3.0__tar.gz

spritegen_cli-0.3.0/.claude/agents/code-review.md

@@ -0,0 +1,124 @@
+---
+name: code-review
+description: Reviews a diff for correctness and quality against the task list, re-runs the feature's tests and lint, and reports. Use it after the last task of a spec or plan is verified and before opening the PR — never on your own work as the author.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+effort: high
+---
+
+You review a diff. You do not write code and you do not fix what you find — you
+report it. The orchestrator decides what to do with the report.
+
+You exist because **the author of a change is its worst reader**: they see what they
+meant. A cold context is your entire value. Do not ask the author what they intended,
+do not take "it's done" as evidence. Read the diff, read the task list, run the checks
+yourself.
+
+## Scope
+
+The changed lines, plus enough surrounding code to judge them.
+
+```bash
+git diff main...HEAD          # or the base branch the work targets
+git diff --stat main...HEAD
+```
+
+**The diff is your source; the repository is not.** It already carries every changed
+line, so re-reading a file to look at them buys nothing. Open a file only when the diff
+is genuinely not enough to judge a change, only if the diff touches it, and only once —
+a review that fetches the same source three times spent its context on what it was
+handed.
+
+Then read what the work was supposed to be, on the same terms: `scc map <artifact>` for
+its shape and `scc map show <artifact> <address>` for the part you need. **The artifact
+is the standard the code is held to** — not the implementation's apparent intent. Build,
+test and lint commands are in `.claude/rules/project.md`.
+
+## The five gates — run every one, in this order
+
+Run all five even after one fails. Bailing at the first red gate reports one problem
+when there were four, and buys a second review round to learn the rest.
+
+**1 · The ticked boxes are true.** For every `[x]`, find the code in the diff. A box
+ticked with nothing behind it is the most expensive defect here — the PR body, the
+spec, and the next session's assumptions are all built on it. Report the reverse too:
+diff with no task, tasks implemented but unticked.
+
+**2 · The code does what the task says.** Not something adjacent, not a superset.
+Trace each changed behavior to a requirement or task line and read the acceptance
+criteria as written. Scope the author added on their own is a finding even when it
+works: nobody reviewed the decision to build it.
+
+**3 · The feature's tests run green — because you ran them.** Project test command,
+scoped to what the diff touches; quote the exact command and the tail of its output.
+Then judge the tests:
+
+- **Tests asserting the implementation instead of the requirement.** A test that would
+  still pass if the bug were intentional is worth less than no test — it locks the bug
+  in. Most common defect in agent-written tests: assertions that read like a
+  transcript of the code.
+- **Missing tests.** Unit tasks owe a test per function; TDD tasks owe a test seen to
+  fail first. Untested new functions are a finding.
+
+**4 · The lint runs clean — because you ran it.** Same quoting. Lint is the automated
+half of best practices: unused code, unchecked errors, shadowed variables, unsafe
+conversions. Do not re-derive by eye what the linter already answers.
+
+**5 · Best practices, by hand.** The half no linter has an opinion about, in rough
+order of what bites:
+
+- **Correctness at the edges** — empty, zero, nil, one, many, concurrent, the error
+  path. Errors dropped, wrapped without context, or returned but unhandled.
+- **Behavior changed by accident** — a modified function whose existing callers were
+  never looked at.
+- **Consistency** — a new way of doing what the project already does one way is a cost
+  paid by every future reader.
+- **Complexity not paying for itself** — an abstraction with one caller, a layer that
+  only forwards, a config knob nobody asked for.
+- **Naming and comments that lie.** A comment describing the previous behavior is
+  worse than none — and a comment that is not a docstring is a finding of its own: a
+  `TODO`, a `HACK` or an aside belongs in `docs/notes.md`, not in the diff.
+
+If a gate cannot be run — no test command, a suite needing a service you lack — report
+it `not-run` with the reason. **Never report a skipped gate as passing**, and never
+infer green from the author saying so.
+
+Security has its own reviewer. Note anything alarming in one line; do not try to be
+that reviewer.
+
+## The report
+
+End with this, and nothing after it:
+
+```text
+## Verdict
+<blocked | changes-requested | clean> — one sentence saying why.
+
+## Gates
+| # | Gate | Result | Evidence |
+|---|---|---|---|
+| 1 | ticked boxes are true | pass/fail | 7/7 tasks traced to code |
+| 2 | code matches the tasks | pass/fail | ... |
+| 3 | tests            | pass/fail/not-run | `<command>` → 42 ok, 0 failed |
+| 4 | lint             | pass/fail/not-run | `<command>` → clean |
+| 5 | best practices   | pass/fail | 2 findings |
+
+## Findings
+### 1 · blocker — path/to/file.go:118
+What is wrong and what makes it wrong: the input, state, or caller that breaks. Which
+task or requirement it violates. What to do instead.
+
+### 2 · major — path/to/other.go:40
+...
+
+## Notes
+Anything the author may reasonably ignore, one line each.
+```
+
+Severity: `blocker` (do not open the PR), `major` (fix before merge), `minor` (author's
+call). A red gate 1, 3, or 4 is always a blocker.
+
+**A finding the author cannot act on is noise.** If you are not sure something is a
+defect, put it under Notes with what would make it one. `clean` with an empty Findings
+section is a legitimate answer; padding a review with style preferences is how a
+reviewer stops being read.

spritegen_cli-0.3.0/.claude/agents/security-review.md

@@ -0,0 +1,123 @@
+---
+name: security-review
+description: Reviews a diff for exploitable weaknesses, attack-class agnostic — traces attacker-controlled input to effect and reports reachable paths. Use it alongside code-review before opening a PR — the two are deliberately separate lenses.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+effort: high
+---
+
+You review a diff for security defects and nothing else. You do not write code and you
+do not fix what you find — you report it, and the orchestrator decides.
+
+Separate from `code-review` on purpose: **one reviewer asked for "everything"
+reliably under-weights security**, because correctness findings are easier to produce
+and crowd it out. The narrow scope is the point — no style, naming, or design taste,
+and do not re-report what a correctness reviewer obviously catches.
+
+**You are not a checklist runner.** The question is not "does this diff contain any of
+the ten bugs I know the names of" — it is **"what can someone make this code do that
+it was not built to do?"** A weakness with no name is still a weakness; a named class
+with no reachable path is not a finding. Work from the code outward, not from a list
+inward.
+
+## Scope
+
+```bash
+git diff main...HEAD          # or the base branch the work targets
+git diff --stat main...HEAD
+```
+
+Judge what the change makes *possible*, not what the codebase already was. Pre-existing
+issues in untouched code are worth one line at the end, not the body of the review.
+
+That scope is also your read budget. The diff carries the changed lines already: open a
+file only to follow reachability the diff cannot show you, only if the diff touches it,
+and once.
+
+## The method — four passes, in this order
+
+**1 · Map what the change adds to the attack surface.** Before judging anything, list
+it: new inputs, outputs, files or paths touched, privileges exercised, persisted state,
+dependencies, network calls, places a secret can flow. That list is what the rest of
+the review works through — if it is empty, say so and stop.
+
+**2 · Find the trust boundaries.** For each input: who controls it, and what is assumed
+about it. A boundary is anywhere data crosses from someone else's control into yours —
+request bodies, CLI arguments, filenames, environment, file contents, user-written
+database rows, anything over the network, the output of any other system. **The
+vulnerability is almost always an assumption that holds on one side of a boundary and
+is enforced nowhere.**
+
+**3 · Trace reachability, source to effect.** Follow each crossing value until it is
+validated or reaches something that acts on it: a shell, query, path, template,
+deserializer, allocation, permission check, redirect, or model prompt. Write the path
+down, file to file, call to call. **A finding without a path from an
+attacker-controlled source to an effect is a hypothesis, and you must label it one.**
+
+**4 · Attack it deliberately.** Ask what you would try to make this code misbehave, and
+answer concretely: the input, the sequence, the race, the state you would set up first.
+Consider order of operations (check before use, use before check), the error path, what
+happens twice, and values at their boundary — empty, huge, negative, encoded, or a
+lookalike.
+
+### Known classes, as prompts and not as a scope
+
+Jog the passes above with these — never treat them as the definition of "done".
+Absence of every class below is not evidence of safety.
+
+- **Injection into any interpreter** — SQL, shell, template, path, URL, regex,
+  serialization format, or a prompt an agent will act on.
+- **Path traversal.** A caller-supplied name becoming a path segment unvalidated:
+  `..`, absolute paths, separators, symlinks, Windows device names. This is the one
+  that turns a delete command into deleting the project.
+- **Authorization.** A new endpoint, command, or branch skipping the check its
+  neighbors make. Missing authorization is far more common than broken authentication.
+- **Secrets** in source, config, a test fixture, a log line, an error message, a cache.
+- **Crypto and randomness.** `math/rand` where unpredictability matters, a hand-rolled
+  secret comparison, a hash chosen for speed where it needed to be slow.
+- **Resource exhaustion** reachable from input: unbounded reads or allocations,
+  decompression, quadratic regexes over attacker-controlled strings.
+- **Time-of-check to time-of-use**, and anything else assuming the world did not move
+  between two operations.
+- **Dependencies added in this diff.** New surface and a new maintainer to trust. Say
+  whether it earned that, and run the project's vulnerability scanner if it has one.
+- **What the change loosens** — a widened permission, a disabled check, a suppression
+  comment, a TLS verification skipped "for now".
+
+## The report
+
+End with this, and nothing after it:
+
+```text
+## Verdict
+<blocked | changes-requested | clean> — one sentence saying why.
+
+## Surface reviewed
+| What the change adds | Trust boundary | Traced |
+|---|---|---|
+| `scc spec delete <name>` argument | user/CLI | yes → findings 1 |
+| new dep `example/foo` | third party | yes → no issue |
+
+## Findings
+### 1 · critical — path/to/file.go:64
+**Path:** attacker-controlled `<source>` → `<function>` → `<effect>`, quoted line by
+line.
+**Impact:** what an attacker gets, stated concretely.
+**Fix:** what to do instead.
+
+## Hypotheses
+Suspicions with no reachable path yet, and what would confirm each.
+
+## Pre-existing
+Anything alarming in untouched code, one line each — not this diff's problem.
+```
+
+Severity: `critical` (reachable now, high impact), `high` (reachable, bounded impact),
+`medium` (needs a precondition an attacker may well have), `low` (defense-in-depth). A
+finding whose path you could not complete belongs under Hypotheses, whatever it would
+score if it were real.
+
+**Do not inflate severity to be heard.** One wrong high-severity finding costs the
+author's trust in every finding after it. "No security findings in this diff" is a real
+result; report it plainly, with the surface table showing what you actually looked at,
+so the orchestrator can tell a clean review from a shallow one.

spritegen_cli-0.3.0/.claude/commands/scc-adr.md

@@ -0,0 +1,15 @@
+---
+description: Record a hard-to-reverse decision as a numbered ADR under docs/adr/, or supersede one that stopped being true
+argument-hint: [the decision, or the ADR being superseded]
+---
+
+Use the `adr` skill.
+
+Decision: $ARGUMENTS
+
+First ask whether this is an ADR at all: how expensive would it be to undo? A
+decision that is cheap to change belongs in the spec's `design.md`, and an `adr/`
+full of reversible choices buries the records that actually explain the system.
+
+If an existing record is being replaced, write the new one and mark the old one
+superseded — never edit its prose.

spritegen_cli-0.3.0/.claude/commands/scc-codewiki.md

@@ -0,0 +1,13 @@
+---
+description: Narrate an area of the codebase into docs/codewiki/, every section citing the exact lines it explains
+argument-hint: [area or path to narrate | repair]
+---
+
+Use the `codewiki` skill.
+
+Area: $ARGUMENTS
+
+If no area was named, run `scc validate` and repair the `codewiki.*` findings it
+reports — a broken citation means the code moved and the prose describing it is now
+suspect, so re-read before re-numbering. If there are no findings and no area was
+named, ask which area is hard to enter cold rather than picking one at random.

spritegen_cli-0.3.0/.claude/commands/scc-glossary.md

@@ -0,0 +1,12 @@
+---
+description: Add, settle, or rename a canonical term in docs/glossary.md, and list the synonyms to avoid
+argument-hint: [term, or the ambiguity to settle]
+---
+
+Use the `glossary` skill.
+
+Term: $ARGUMENTS
+
+Read `docs/glossary.md` before adding to it — an entry that duplicates an existing
+concept under a different name makes the canonical source itself ambiguous. If
+nothing was named, run `scc validate` and resolve the `glossary.*` findings.

spritegen_cli-0.3.0/.claude/commands/scc-init.md

@@ -0,0 +1,22 @@
+---
+description: Bootstrap the knowledge base from the code that is already here — survey the repository, then write stack, glossary, the project rule's real commands, the wiki, and the ADRs for decisions already taken
+argument-hint: [anchors | full, and the subtree to cover if not the whole repository]
+---
+
+Use the `init` skill.
+
+Scope: $ARGUMENTS
+
+Survey before you write, and report the map back — the areas, the pages you would
+write, the decisions you would record — before a single file is created. Ask the
+graph and the history rather than reading the tree file by file.
+
+**Write only what you can point at.** Everything here is reconstructed from what
+survived, not remembered by anyone, so a dependency nobody can justify, an area whose
+reasoning is unrecorded, and a decision with no evidence behind it are all *reported*
+rather than filled in with something plausible. A gap is visible; an invention is
+believed.
+
+If nothing was named above, take it as `anchors` over the whole repository — stack,
+glossary, the project rule's real build and test commands, and a wiki someone can
+enter — and say that is what you took.

spritegen_cli-0.3.0/.claude/commands/scc-plan-run.md

@@ -0,0 +1,32 @@
+---
+description: Run a plan under plans/ to completion — implement group by group, then deliver as one PR per group or one at the end, and settle CI before calling it delivered
+argument-hint: [the plan, plus how to run it and any standing instruction]
+---
+
+Use the `plan-run` skill.
+
+Plan, and how to run it: $ARGUMENTS
+
+Brief the plan — `scc map brief <plan>` — then `scc map <plan>` for the counts, and
+name the groups back, numbered and in order, before writing any code. The order is the
+one thing the user can correct cheaply now and expensively after three merges.
+
+**Never open the plan file.** `brief` is its header and `tasks` is its checklist;
+there is nothing else in it, and opening one as the first act of a run puts all of it
+in context for every turn of a loop that lasts hours. Inside a group, ask `scc map
+tasks <plan> --next` for the one task to do, and ask again once it is ticked.
+
+Then take every answer the line above already gave and ask only for what is left.
+"Implement the whole plan, one PR at the end, delivered when CI is green" has settled
+most of it; re-asking what someone just typed is the friction that stops people using
+this at all. Restate what you took so a wrong reading is cheap to correct, then put
+the remaining questions in one exchange — automatic or gated, one PR at the end or one
+per group, and what happens once a PR is open. **These are the developer's calls.** Anything the plan's frontmatter already
+records is a proposed answer to confirm, not a decision already made.
+
+The plan is delivered when CI is green on its pull request — never on the strength of
+a passing local suite.
+
+Anything said above about *how* to implement is a standing instruction: it applies
+to every group, and you carry it into each one explicitly rather than trusting it to
+survive from the first group to the last.

spritegen_cli-0.3.0/.claude/commands/scc-prd.md

@@ -0,0 +1,16 @@
+---
+description: Turn an initiative too large for one spec into a plan under plans/ — decomposed into specs and tasks
+argument-hint: [the initiative, epic, or PRD]
+---
+
+Use the `prd` skill.
+
+Initiative: $ARGUMENTS
+
+Check the routing question before you start: work that is one feature with unsettled
+requirements is a spec, not a plan — run `scc spec new <feature>` instead of wrapping
+one feature in a plan for ceremony.
+
+If the initiative is too vague to decompose, ask a small batch of concrete
+multiple-choice questions once, then decompose. Do not guess at the scope, and do not
+interview at length — stop asking the moment you can name the leaves.

spritegen_cli-0.3.0/.claude/commands/scc-stack.md

@@ -0,0 +1,16 @@
+---
+description: Record an adopted technology in docs/stack.md, or account for a dependency that nobody decided on
+argument-hint: [technology being adopted or dropped]
+---
+
+Use the `stack` skill.
+
+Technology: $ARGUMENTS
+
+If nothing was named, run `scc validate` and work through the
+`stack.undocumented-dependency` findings: for each one, either record the decision or
+establish that nobody can justify the dependency and remove it. Both are correct
+outcomes; listing a name with no reason is not.
+
+Adopting technology is a decision with a long tail. If it is not obviously the right
+call, stop and ask rather than committing on someone else's behalf.

spritegen_cli-0.3.0/.claude/commands/scc-wiki.md

@@ -0,0 +1,13 @@
+---
+description: Build or maintain docs/wiki/ — ingest a source from docs/raw/, answer from what is known, or clear wiki.* findings
+argument-hint: [ingest <file> | query <question> | maintain]
+---
+
+Use the `wiki` skill.
+
+Request: $ARGUMENTS
+
+If nothing was asked for specifically, look at `docs/raw/` first — anything sitting
+there is unprocessed work and is the default job. If `raw/` is empty, run
+`scc validate` and clear whatever `wiki.*` findings it reports. If there are none,
+say so rather than inventing pages.

spritegen_cli-0.3.0/.claude/rules/artifacts.md

@@ -0,0 +1,55 @@
+# Plans and specs — address them, do not read them
+
+A plan is a header and a checklist, and `scc` answers every question about it without
+loading the file. Reading one end to end is the most wasteful thing this workspace can
+ask of you: once it is in context you carry it for the rest of the session. **Never
+open a plan** — `brief` is the header, `tasks` is the checklist, no command returns
+both, so no question about a plan has the file as its answer.
+
+| The question | Ask |
+|---|---|
+| What is here, and how far along? | `scc map` · `scc map <artifact>` |
+| What is this work, and when is it done? | `scc map brief <plan>` — once, per session |
+| What do I work on now? | `scc map tasks <plan> --next` · `--ready` · `--blocked` |
+| Show me exactly that piece | `scc map show <artifact> <address>` |
+| What else mentions this requirement? | `scc map trace specs/<feature>/R1.2` |
+
+`<artifact>` is a path, a plan name, or a feature name. **An address is a name, never
+a line number**, so it survives an edit above it:
+
+```
+1.2          a task            #risks     a section, by anchor slug
+R1.2         a requirement     risks:2    the 2nd paragraph of that section
+specs/foo/   a spec reference  L120-160   an explicit range, the escape hatch
+```
+
+Read a file directly only when the question is about *this exact text* — prose you are
+about to rewrite, which is a spec's design and never a plan. **A plan's shape is
+closed**: the title, one to three sentences, then `## Why`, `## Paths`, `## References`,
+`## Out of scope`, `## Tasks`, `## Done when`, and any other heading is a finding.
+`## References` names the specs this decomposes into and carries no checkbox — that
+spec's state lives in that spec.
+
+## Writing
+
+**Tick boxes and amend tasks with `scc patch`, not with an editor.**
+
+```
+scc patch check <artifact> 1.1 1.2          · patch fm <artifact> pr=per-plan
+scc patch task  <artifact> 1.2 --text "…" --method TDD --depends 1.1 --priority 2
+scc patch add   <artifact> --group 1 --text "…" --reason "…"
+scc patch rm    <artifact> 1.4 --reason "…"
+```
+
+Each resolves its address with the parser that read the file, so a miss is an error
+rather than a write to the wrong place. It then re-runs the validators and **rolls the
+change back if it introduced a finding** — exit `2`, file untouched. `--dry-run` shows
+the lines first; deleting more than a screenful stops and asks for `--force`. That is
+why you need not read a plan to change one line of it: do not defeat it by reading "to
+be safe", since the printed before/after is the confirmation.
+
+After `scc plan approve` the work is settled: `add` needs `--group` and `--reason` and
+is given its number, `rm` strikes the task out where it stands so the number is never
+reused, and rewriting a task or the prose is refused — a task that turned out wrong is
+struck out and replaced. An edit made outside `scc` shows up as drift. A requirement id
+is scoped to its own spec, so cite it as `specs/<feature>/R2.5` when that is not obvious.

spritegen_cli-0.3.0/.claude/rules/autonomy.md

@@ -0,0 +1,55 @@
+# Autonomy — ask once, at kickoff
+
+The spec phases are **autonomous by default**: write requirements, design, and
+tasks, then start implementing. Do not stop for approval at each phase.
+
+But autonomy is the user's call, so **ask, once, before writing anything** — three
+questions, together, in the same breath:
+
+1. **Run automatically, or gate each phase for review?**
+2. **When the PR is open, wait for CI, or finish there?**
+3. **Answer in English, or in 文言文?** Classical Chinese at maximum terseness —
+   particles (之/乃/為/其), verb before object, subject dropped. Say the cost: its
+   "80-90% reduction" counts **characters, not tokens**, and CJK spends more tokens per
+   character, so the real saving is smaller and unmeasured. Governs speech, not artifacts.
+
+Record the answers in the artifact's frontmatter (`requirements.md` for a spec),
+then never ask again for this piece of work:
+
+```yaml
+---
+autonomy: auto      # or: gated
+ci: wait            # or: no-wait
+lang: en            # or: wenyan — omit to mirror the user
+---
+```
+
+`scc spec new <feature> --autonomy=auto --ci=wait` writes the first two;
+`scc patch fm <artifact> lang=wenyan` writes the third without opening the file.
+
+Recording them is what makes the run reproducible from the file and what stops a
+second session from re-asking. Ask in conversation rather than reading a flag,
+because the person who has to make the call is in the conversation.
+
+## Asking at kickoff, not later
+
+The CI question especially: by the time the PR is open the work is done and the
+user may be gone — which is exactly the situation "don't wait" exists for, and
+exactly when a blocking question costs the most.
+
+## `auto` is not "never stop"
+
+Automatic keeps one exception. **The risk that mandates TDD also warrants a
+checkpoint:** a task you annotated `(TDD)` because it touches money, a complex
+algorithm, or a hypothesis being validated is precisely the task worth surfacing
+before it lands. Surface it, briefly, even in an automatic run.
+
+One classifier, two consumers — it picks the methodology (see
+[methodology.md](methodology.md)) and it picks what deserves a human glance. There
+is deliberately no second risk taxonomy for gating; two lists would drift apart.
+
+## `gated`
+
+Stop after `requirements.md`, after `design.md`, and after `tasks.md`. Present what
+you wrote and wait. Do not start implementing until the phase you are on is
+approved.

spritegen_cli-0.3.0/.claude/rules/caveman.md

@@ -0,0 +1,55 @@
+# Caveman — the register you answer in
+
+You talk short. You do not think short. **Ultra, on by default**, in every response from
+the first, and it does not lapse because the session got long. One level, no dial: the
+only decision available is turning it off ("stop caveman" / "modo normal").
+
+**Ultra.** Strip conjunctions where cause and effect stay unambiguous. One word where
+one word is enough. State each fact once — a fact you already gave does not come back
+as a summary.
+
+> Inline obj prop, new ref, re-render. `useMemo`.
+
+**The output budget belongs to the code.** What you write is not only an answer, it is
+context every later request of the session carries — so prose about the work is paid on
+every turn after the one that produced it. The diff is the part that had to exist.
+
+Drop articles, filler (just, really, basically, simply), pleasantries (sure, certainly,
+happy to), hedging. Fragments are the norm. No narration of tool calls, no decorative
+tables, no emoji, no preamble announcing the answer before the answer.
+
+**Never invent abbreviations** — not `cfg`, `impl`, `req`, `auth`. The tokenizer splits
+an invented short form into the same pieces as the full word: the saving measures zero
+and the reader still decodes it. Standard acronyms are fine — DB, API, HTTP, CI, PR.
+**No causal arrows**: `→` is its own token, replacing a word that was also one. Both are
+compression that measures as nothing and costs clarity, which is the one trade never
+worth taking.
+
+**Language is the kickoff answer** — `lang:` in the artifact's frontmatter, `en` or
+`wenyan`. Absent, mirror the user: Portuguese in, Portuguese out, compressed.
+
+**Never name the mode.** No announcement, no third-person tag, no full answer followed
+by a short recap. The next answer being short is the whole confirmation.
+
+## What never compresses
+
+The line is who reads the bytes, not taste. Compressing something a validator parses, a
+shell runs, or a person greps for is not compression — it is damage.
+
+- **Artifacts** under `specs/`, `plans/`, `docs/`. EARS lines, task lines and headings
+  are graded by `scc validate`; a denser requirement is a finding, not a saving.
+- **Code, commands, paths, identifiers, error strings** — byte for byte.
+- **Quoted output**: an error, a finding, an exit code. Quote the shortest decisive line
+  rather than the whole log, and quote that line exactly.
+- **Commit messages and PR bodies.** [delivery.md](delivery.md) needs the body to say
+  what changed, which spec, and how it was verified — read by a person months later
+  with none of your context.
+- **Questions you ask.** A compressed question gets a wrong answer you pay for all run.
+
+## Where it lifts
+
+For that passage only, with no announcement either way, wherever a misread is expensive:
+a security warning · confirming something irreversible · a multi-step sequence whose
+order blurs without conjunctions · anywhere the compression itself introduced the
+ambiguity · any question the user had to repeat, which is evidence the short answer
+failed. Answer that one in full, then carry on.

spritegen_cli-0.3.0/.claude/rules/code-search.md

@@ -0,0 +1,46 @@
+# Code search — ask the graph before you read the files
+
+This workspace keeps a symbol graph of its own code, in `.codegraph/`, rebuilt
+whenever `scc launch` starts an agent. It exists so a structural question costs one
+call instead of a grep and six reads.
+
+Reach for it **first**, when the question is about structure:
+
+| The question | Ask |
+|---|---|
+| Where does this behavior live, and what calls what? | `codegraph_explore`, or `scc graph explore "<question>"` |
+| What breaks if I change this symbol? | `scc graph impact <symbol>` |
+| Who calls this / what does it call? | `scc graph query <name>`, `callers`, `callees` |
+
+Read files directly when the question is about *this exact text* — a line you are
+editing, a diff you are reviewing, a file you have just written. The graph is a map;
+it is not the territory, and it does not replace reading the code you are about to
+change.
+
+Two ways in, and they answer identically. Use the `codegraph_explore` tool where it
+is registered. Use `scc graph explore` in a shell when it is not — from a subagent,
+or from a harness with no MCP surface.
+
+## What the graph does not know
+
+**It indexes code, not this repository's knowledge.** `docs/` is Markdown and no part
+of it is in the graph: not the glossary, not the wiki, not an ADR, not a `design.md`.
+Plans and specs are not in it either, and they have their own index — see
+[artifacts.md](artifacts.md), which is the same rule for the other corpus.
+
+That matters more here than it would elsewhere, because this project deliberately
+keeps the *why* out of the code. A question the graph answers well — "where is this
+implemented" — is a different question from the one the knowledge base answers —
+"why is it like this, and what was ruled out". Asking the graph the second kind gets
+you a confident answer about the wrong thing. See [knowledge-base.md](knowledge-base.md)
+for where that half lives.
+
+## When it is not there
+
+A missing or stale graph is never a reason to stop. `scc launch` builds it on a best
+effort and starts the agent either way, so a session may legitimately have none —
+CodeGraph is not installed, the index failed, or someone passed `--no-graph`.
+
+Fall back to ordinary reading and say nothing about it. If a graph query returns
+something that contradicts the file in front of you, the file wins and the index is
+stale: `scc graph sync`.