@outerlayer/cli 0.2.0 → 0.4.1

package/skill-pack/template/spec/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: spec
+description: >
+  Turn an idea into an approved issue: search for duplicates, draft acceptance
+  criteria with their proof forms, split work that is too big for one story,
+  and file it after you approve it. Then offer to start the build. Use when you
+  want to write up a feature or change before building it. Invoke with
+  /spec <what you want built>.
+---
+
+Take one idea from a sentence to an issue a person can build from. This file
+is the procedure. The content discipline is the `writing-specs` skill: summary
+block, problem before solution, non-goals and Given/When/Then criteria. Follow
+it, and do not restate it here.
+
+This skill files the issue. It does not branch, write code or run tests.
+`/build` does that, on a work item that names the issue.
+
+## Arguments
+
+Everything after `/spec` is what you want built. One optional form: an issue
+reference, such as `#<n>` or a Linear or Jira key. It means revise the spec in
+that issue in place instead of filing a new one. Skip step 1, because there is
+nothing to de-duplicate against, and let the filing step edit that issue.
+Every other step runs, the reader pass included.
+
+## Steps
+
+Run them in order. Do not skip the approval.
+
+1. **Scope.** Restate the request in one or two sentences. Search open and
+   recently closed issues through the team's tracker tool for a duplicate or a
+   parent. Quote what you searched and what you found. Show the user a
+   near-duplicate before drafting anything. Filing a second issue for work
+   already tracked is the failure this step prevents.
+2. **Draft.** Write the spec as `writing-specs` describes. Put the criteria
+   under an `## Acceptance criteria` heading, each in Given/When/Then form with
+   a stable id the team chooses. Every criterion whose outcome a user can see
+   carries a proof form beside its id: `(proof: video)` for a flow of more than
+   one step, and `(proof: screenshot)` for a single state. A test is the proof
+   only where nothing visible changes. A criterion nobody can prove is a
+   criterion nobody can build to, so give every one either a proof form or a
+   named test.
+3. **Size.** More than twenty-four criteria is not one story. Above that, show
+   the work already split into slices that each stand alone. Slice one carries
+   the criteria the others depend on, and the rest become their own specs. The
+   user may redraw the split. Skipping it is not on offer.
+4. **Reader pass.** Send the title and body through one cold rewrite agent. Its
+   only inputs are the draft and one writing rule: write for a reader who was
+   not in this conversation, lead with the outcome, keep sentences under about
+   twenty words, and use plain words. It never sees this conversation. Criteria keep
+   their exact wording. Check that every path, identifier, number and link
+   survived, and restore anything the rewrite dropped.
+5. **Checkpoint.** Show the drafted title and body and the criteria with their
+   proof forms, and wait for explicit approval. Before showing them, check every
+   criterion: it has an id, a Given, When and Then, and a proof form or a named
+   test. A criterion that fails the check goes back to step 2. Apply requested
+   edits, run the reader pass again over the edited text, and show it again
+   until approved. Nothing is filed before this point. A spec the user rejects
+   leaves no issue behind.
+6. **File it.** Through the team's tracker tool, file the approved title, body
+   and full criteria. Then file the slices from step 3, and only the ones the
+   user named. The issue is the source of truth from here on. Note its
+   reference exactly as the tracker gives it: a number, or a Linear or Jira key.
+7. **Ask whether to build.** Ask the user exactly one question: build it now, or
+   not yet. Never start work unasked, because the user may want to hold the
+   issue.
+8. **Start the build.** On a yes, run `outerlayer work build --issue <reference>`,
+   where the reference is the issue number or the Linear or Jira key exactly as
+   the user typed it. Print the item number the command reports and the launch
+   line:
+
+       OUTERLAYER_WORK=<number> claude "/build"
+
+   If the command is refused, the error says why. Relay it, show the command for
+   the user to run later, and stop. If the CLI rejects a flag named here, run
+   `outerlayer work build --help`, follow what it prints, and say that this
+   skill's text is behind the CLI. On a no, show both commands for later and
+   stop.
+
+## Scope limits
+
+One `/spec` files one issue, plus the slices the user approves in step 3. It
+files nothing in another repository. It never creates a branch or edits code.

package/skill-pack/template/writing-specs/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: writing-specs
+description: How to write a feature spec: problem framing, goals and non-goals, assumptions, and acceptance criteria in Given/When/Then, before implementation begins. Use when asked to "write a spec", "spec this out", "write a PRD", "draft acceptance criteria", or when shaping the issue for a new feature.
+---
+
+# Writing Specs
+
+A spec is the agreement about what to build, made before building it. It lives
+in the issue body: one clean spec, edited in place as the shape is agreed,
+never a trail of amendment comments. Its acceptance criteria sit under an
+`## Acceptance criteria` heading. Each criterion has an id, and an id is any
+stable label the team chooses, such as `LOGIN-01` or `AC-12-03`. Pick a scheme
+once and keep to it. Planning scratch is local and disposable. Nothing durable
+belongs there.
+
+## Lead with a summary block
+
+A spec is triaged before it is read. Someone lands on it and needs, within
+thirty seconds: what this is, what blocks it, roughly how big, and what is
+deliberately not in it. Prose cannot answer that, however good it is. So every
+issue-body spec opens with a block that does, before the problem statement:
+
+- **In one line**: what changes, in a sentence.
+- **Blocked by / blocks**: issue references, and any step that is a person
+  doing a thing rather than a merge, such as a provider setting, an approval or
+  a credential. Those silently become the critical path.
+- **Size**: small, medium or big. Not an estimate and not a commitment.
+- **Not in scope**: the neighbouring work this will be confused with, and where
+  it lives instead.
+- **Criteria count**, so a reader knows the shape before scrolling.
+- **The invariants to defend in review**: the handful of things a well-meaning
+  reviewer will try to negotiate away.
+
+Then give the reason for the single decision most likely to be reopened. If it
+took research to settle, the summary is where the finding goes. A reader who
+has to reconstruct it will re-litigate it.
+
+Regenerate the block whenever the body is amended. A spec edited in place under
+a summary that no longer matches it is worse than one with no summary.
+
+## Problem before solution
+
+Open with the pain: who hits it, when, and what it costs them. A concrete
+scenario beats an abstract claim, and data beats both. "The app can't do X" is
+a solution in disguise. If the problem statement already names the feature, the
+problem has not been framed. Everything after this paragraph is judged by
+whether it relieves the stated pain.
+
+## Goals and non-goals
+
+State what done looks like: outcomes that can fail, not aspirations. Spend
+equal care on non-goals. An exclusion left unstated does not stay excluded. It
+returns as scope creep in review, or as a guess by whoever implements. "Deferred,
+not dropped" is a valid non-goal. Say which one it is, so the reader knows
+whether to expect it later.
+
+## Alternatives and assumptions
+
+Name the alternatives considered and why each lost. Without the rejection
+reasons, a later reader can only blindly accept the design or blindly reopen it.
+Label assumptions as assumptions, each with its blast radius: "we assume X; if
+wrong, Y changes." An assumption stated as fact is the spec's most durable lie.
+
+## Prior art and rabbit holes
+
+Two sections that earn their place only when there is something real to put in
+them, and are lost forever when there is and they are missing.
+
+**Prior art.** How others solved this, and what they settled on. Where it came
+from research, name the source. A team that cannot see the prior art re-derives
+a solved problem later, or reopens a decision already made against evidence.
+
+**Rabbit holes.** The specific places this eats a week if nobody is warned. It
+differs from its neighbours. Non-goals say what we will not build. Assumptions
+say what might be wrong. A rabbit hole says this part looks small and is not.
+Name it, and say what the cheap escape is.
+
+## Weight matches ambiguity
+
+Scale the document to the uncertainty, not to a template. A bounded change earns
+a paragraph and a handful of criteria. A full spec is for genuine ambiguity in
+the problem or the solution. Never fill a section for completeness. An empty
+section costs the reader more than its absence, and padding dilutes the intent
+it surrounds.
+
+## Writing criteria
+
+Criteria are the definition of done, extracted from the agreed spec before
+implementing. Never write them by reading the finished implementation back.
+
+- **One behavior per criterion.** A Given/When/Then that needs a second When is
+  two criteria. So is a Then joining unrelated outcomes with "and".
+- **An observable, pass/fail Then.** If no test could fail it, it promises
+  nothing. Ban vague adjectives such as "fast", "gracefully" and "user-friendly".
+  State the number or the behavior instead.
+- **Declarative wording.** Litmus: would this sentence change if the
+  implementation did? "When Bob logs in", not "when Bob clicks Submit on
+  /login". Declarative criteria survive refactors and read as product truth.
+- **Every promised error path gets its own criterion.** An unstated edge case
+  is not left open. It is guessed at during implementation.
+- **`(proof: ...)` between the id and Given** when a criterion needs
+  human-visible evidence. Use `video` for a flow of more than one step and
+  `screenshot` for a single state. A test is the proof only where nothing visible
+  changes. The proof shows the running page, never a component render. The
+  emitting-evidence skill covers capture.
+
+## Honest limits
+
+A criterion may carry prose admitting what it does not cover. Useful idioms:
+**Knowingly accepted gap:** with the reason and the path to closing it, and
+**TODO:** for deferred-not-dropped scope. When part of a promise is a
+performance target or a judgment call no test can assert, say what the bound
+tests prove and what they do not. A spec claiming more than its tests prove is
+the more dangerous artifact. Write the limit down instead.
+
+## Amendments
+
+When implementation shows the spec was wrong, amend the issue in place and note
+the owner's ruling in the body. Retire a criterion by deleting the line and its
+test citation together. Never renumber ids.
+
+## The reader test
+
+Before calling a spec done, hand it to a fresh agent with no conversation
+context and ask: what would you build, what is ambiguous, what would you have to
+guess? Whatever the cold reader gets wrong is a bug in the spec, not in the
+reader. Fix the wording, then get the owner's sign-off before any
+implementation.
+
+This is the only rule here that catches what the author cannot see, so it is
+the one most often skipped. Re-reading your own spec does not satisfy it. Run it
+against the issue body as published, not the draft in the working tree. A spec
+whose design lives in links the reader cannot follow fails this test, and that
+failure is invisible to whoever wrote it.