@dsdenes/devboard 0.1.560 → 0.1.562

package/prompts/prepare-skills.md

@@ -0,0 +1,142 @@
+---
+description: Prepare project-agnostic Agent Skills grounded in relevant public standards, general best practices, software-architecture patterns, and testing patterns selected from GOAL.md.
+---
+
+`/prepare-skills`: derive a focused set of project-agnostic Agent Skills from the goal, grounded in
+current public practice, and leave no contradictions among the installed skills.
+
+## Contract
+
+- `<host>` is the host project: `git rev-parse --show-toplevel`; when that fails, the working
+  directory. `.devboard/` and `.worktree/` are the harness, not the host; never write into them.
+- `<host>/GOAL.md` is the only project-specific input. Read it once and use it only to select which
+  public standards and pattern families are relevant to the work it describes. Never copy, quote,
+  paraphrase, summarize, or allude to its implementation details in a skill.
+- Every skill is project-agnostic: it states policy that another project could adopt unchanged.
+  Implementation decisions stay with the implementation agent, never with a skill.
+- Do not survey, list, or read host source code, `adrs/`, configuration, package manifests, build
+  files, tests, README files, or directory trees. Do not infer implementation facts the goal does
+  not state, and do not ask the developer for them.
+- Deliverable: skills under `<host>/.omp/skills/<name>/SKILL.md`, each with a directory name that
+  matches its frontmatter `name`. Create nothing outside that skill root except the directories and
+  `SKILL.md` files themselves.
+- NEVER write, rewrite, or delete `<host>/GOAL.md`, anything under `<host>/adrs/`, or any other
+  host file.
+- Replace only the skills this feature owns. At the start, delete every skill directory whose
+  `SKILL.md` frontmatter has `metadata.devboard-managed: "true"` and does not carry
+  `metadata.devboard-family: "discover"`. A managed skill with no `metadata.devboard-family` field
+  belongs to this prepare family for backward compatibility. Never delete, rename, or edit a skill
+  that does not belong to this family, including a Discover-family skill: the Discover family is
+  project-specific, owned by Discover, and belongs to the developer once it is published.
+- Install no third-party skill. `npx skills` may be used only to inspect or adapt public skill
+  content while authoring; every delivered `SKILL.md` is written locally for this goal.
+
+## Phase 1 — Goal and research
+
+1. Read `<host>/GOAL.md`. If it is absent, empty, or whitespace-only, `halt: GOAL.md is not set`
+   and nothing else.
+2. Treat the goal as a selection signal only: decide which standards and pattern families it makes
+   relevant. Never turn a statement from it into a skill directive.
+3. Research current public practice on the web before writing anything. Search separately in each
+   of these areas and read enough sources to distinguish durable guidance from fashion:
+   - public standards and specifications from authoritative bodies, such as RFCs, ISO or IEEE
+     standards, and standards-organization guidance;
+   - general engineering best practices that apply regardless of stack or organization;
+   - software-architecture patterns: boundaries, dependency direction, cohesion, coupling,
+     interfaces, layering;
+   - testing patterns: test boundaries, observable behavior, test doubles, regression coverage.
+   Prefer primary sources and official guidance. Record what the sources say well enough to explain
+   it, not to copy it.
+4. Do not fabricate research. If web access fails, `halt: web research is unavailable` and write no
+   skill.
+
+## Phase 2 — Choose the skills
+
+Decide how many skills to prepare and what each one covers. Base the choice on the standards and
+pattern families the goal makes relevant, not on a fixed taxonomy. At least one skill is required;
+there is no maximum and no required topic. Each skill covers one coherent family so another project
+can adopt it unchanged.
+
+## Phase 3 — Interview when needed
+
+Ask at most one round of questions, and only when the goal leaves open which standards or pattern
+families matter for the prepared skills. Use the `ask` tool with 2–5 concrete options, then
+continue. Do not ask about technology, language, framework, or file layout, and never ask for
+implementation detail the goal does not state. No question is required when the goal is specific
+enough.
+
+## Phase 4 — Author the skills
+
+Write at least one skill. Each is one directory under `<host>/.omp/skills/` containing one
+`SKILL.md`. Use this shape:
+
+```markdown
+---
+name: lower-case-hyphenated-name
+description: One sentence naming the policy the skill states and when to apply it.
+metadata:
+  devboard-managed: "true"
+  devboard-family: "prepare"
+---
+
+# Title
+
+- One portable policy per bullet, phrased as an imperative.
+- Another policy drawn from a public standard or a named pattern.
+```
+
+Rules for every skill:
+
+- It is project-agnostic: another project with a different stack can adopt every directive
+  unchanged.
+- It contains no project-specific implementation detail: no host or product name, no repository or
+  absolute path, no host directory or file name, no module, class, function, type, package,
+  dependency, framework, runtime, library, or programming language, no data format, API shape,
+  schema, or configuration key, and no concrete architecture, layout, or design decision.
+- Public domain names, formats, and standard identifiers are allowed when they are the subject of
+  the guidance, such as an RFC number, a named standard, or a protocol defined by a public body.
+- Directory name equals `name`, matches `^[a-z0-9]+(-[a-z0-9]+)*$`, and is at most 64 characters.
+- `description` is non-empty, at most 1024 characters, and states the policy the skill governs and
+  when an agent should apply it.
+- Body guidance states durable policy grounded in the researched standards and patterns, not
+  generic filler such as "write clean code" or "test your code".
+- Guidance is internally consistent and complements rather than repeats the other skills.
+- State directives explicitly, one policy per bullet, so a later review can compare them.
+- A skill carries no provenance line, source list, or citation field; the research informs the
+  policy and stays out of the delivered file.
+
+## Phase 5 — Review every installed skill
+
+This pass is mandatory and covers every skill in `<host>/.omp/skills/` that belongs to this
+prepare family, plus every hand-authored skill without a `devboard-managed` marker. It never reads
+a skill whose frontmatter carries `metadata.devboard-family: "discover"`: Discover's
+project-specific policy is not measured against project-agnostic preparation.
+
+1. List every skill directory and read every `SKILL.md` in it.
+2. Extract the directive statements: bullets or lines beginning with a policy word such as
+   `Always`, `Never`, `Must`, `Should`, `Do not`, `Avoid`, `Prefer`, or `Use`.
+3. Compare each pair of skills. Two skills contradict when they state opposite policies for the
+   same subject, for example "Always use dependency injection" and "Never use dependency
+   injection".
+4. Resolve every contradiction by rewriting a skill of this prepare family so both give compatible
+   instructions. You may rephrase, narrow, merge, or delete prepare-family skills. Never change an
+   unmanaged skill or a Discover-family skill.
+5. If a contradiction cannot be resolved without changing an unmanaged skill, stop: leave the
+   unmanaged file exactly as it was and `halt: unresolvable contradiction with unmanaged skill
+   <name>`. Do not claim success.
+
+## Phase 6 — Finish
+
+- Every skill of this family must carry both markers, and the prepare family must contain at least
+  one skill.
+- The final review must have no remaining contradictions.
+- Reply with a short list of the prepared skill names and `No contradictions`; never paste skill
+  bodies into chat.
+
+## Halting
+
+`halt: <reason>` on its own line and nothing else. Reasons: `GOAL.md` is absent, empty, or
+whitespace-only; web research is unavailable; the skill root cannot be written; a contradiction with
+an unmanaged skill cannot be resolved without editing that skill.
+
+NEVER halt for effort, question count, model latency, or the number of research queries.

package/prompts/scout-recommendations.md

@@ -0,0 +1,143 @@
+---
+description: Survey the host repository and write the significant, evidence-backed improvement recommendations Auto Scout files as issues.
+---
+
+`/scout-recommendations`: survey the repository, find significant improvements, and write the
+recommendations to the scan file Auto Scout named. This turn produces a recommendation document,
+nothing else.
+
+## Contract
+
+- The scan directory is the command argument, absolute and outside your control:
+  `<scan-dir>`. Read `<scan-dir>/request.json` once; it carries `requested`, `categories`,
+  `excludedRoots`, `knownTitles`, `draftGoalHeadings`, `significanceThreshold`, and
+  `repositoryPath`.
+- `<repositoryPath>` is the repository to survey. Never survey or write outside it, and never
+  read inside an `excludedRoots` tree: generated output, vendored packages, temporary state, and
+  worktrees are not the repository under review. Every `path` you cite is relative to that exact
+  root: a file under a subdirectory keeps that leading directory in the path, never a shorter
+  form. Before writing the answer, confirm every cited path with `test -f <path>` from
+  `<repositoryPath>`.
+- One correction turn is available: if validation rejects the answer, rewrite
+  `<scan-dir>/recommendations.json` addressing exactly what the rejection names.
+- Read the repository's context files (`AGENTS.md`, `GOAL.md`, `README.md`, `adrs/`, `docs/`), its
+  package manifests, its source, and its tests before proposing anything. A finding you cannot
+  point at in the code is not a finding.
+- Deliverable: exactly one file, `<scan-dir>/recommendations.json`. Write nothing else, anywhere.
+- Never modify the repository: no edits, no formatting, no new files inside it, no branches,
+  commits, stashes, builds, tests, installs, or any command that mutates the checkout or its git
+  state. Read-only inspection only.
+- Never file an issue, write a draft goal, or touch `.devboard/goal-proposals/`.
+- Never ask the developer a question, request permission, or wait for input. Decide with what the
+  repository shows, finish in this one turn, and write the file.
+- The delivered count is at most `requested`. Fewer significant findings than requested is a
+  correct answer, with a non-empty `shortfall` reason. Never pad the list, never invent filler,
+  and never repeat a finding to reach the count.
+- `knownTitles` is the normalized form of every existing Auto Scout issue title and every open
+  issue title; `draftGoalHeadings` is every draft goal heading. Never restate, paraphrase, or
+  split one of those findings: the worker drops such an item and records it.
+
+## Significance
+
+Every item carries an integer `significance` from 1 to 5 and a non-empty `significanceReason`.
+Score honestly; the worker files only items scored 4 or 5, so an inflated score wastes a filing
+slot and an honest 3 is a correct answer.
+
+- **4 or 5 requires a named, observable impact.** Name one of: a reproducible defect, a real
+  failure mode (an input, state, or ordering that makes the code do the wrong thing), or a
+  measured structural cost (a duplicated rule whose copies already disagree, a measured build or
+  runtime cost, a boundary with no test that would let a real regression pass).
+  - 5: the impact is reachable now and correctness- or data-affecting.
+  - 4: the impact is real and named, but narrower or latent.
+- **3:** a real observation with no observable impact named yet — a latent inconsistency, an
+  unexercised cleanup, a structural preference. Do not file it.
+- **2 or 1:** polishing code that is already correct, style, formatting, comment wording, a
+  speculative rewrite, or a generic "add tests" item with no named gap. Never a deliverable.
+
+`significanceReason` states the impact in one or two sentences. "It would be cleaner" is not an
+impact. "`parseA` and `parseB` disagree on a trailing slash, so a path with one is rejected by
+the first and accepted by the second" is.
+
+## What to survey
+
+Read widely enough to judge significance, then look for:
+
+- duplication: the same logic, rule, or literal in several places that should be one;
+- unclear or inconsistent naming: one concept under two names, or a name that promises something
+  the code does not do;
+- entities that should merge or split: a module doing two jobs, or two modules that only work
+  together;
+- long or tangled units: a function or component whose branches hide its intent;
+- missing or weak tests: a named behavior, boundary, or failure path with no test, or a test that
+  cannot fail;
+- unhandled inputs and failures: an unchecked external value, a filesystem or network call with no
+  failure path, a promise nobody awaits;
+- swallowed errors: a `catch` that discards the reason, a fallback that hides a real failure;
+- race or ordering hazards: shared state written from two paths, work that assumes an order the
+  code does not enforce.
+
+Prefer one high-impact finding over three easy ones. A finding earns its place only if fixing it
+changes behavior, correctness, or the cost of the next change.
+
+## What never ships
+
+Do not propose: style or formatting preferences; comment-only changes; speculative rewrites with
+no defect named; a dependency, framework, or architecture swap as an end in itself; a generic
+"add tests" item with no named gap; or anything already filed, open as an issue, or present as a
+draft goal. Those titles are in the request; never restate them, and never propose a paraphrase
+of one.
+
+Every item must cite at least one concrete `path:lines` inside the repository and at least one
+acceptance criterion an implementer can verify by running something.
+
+## Output
+
+Write `<scan-dir>/recommendations.json` as one JSON object:
+
+```json
+{
+  "recommendations": [
+    {
+      "category": "clarity",
+      "title": "One line, at most 200 characters, no trailing period",
+      "summary": "What is wrong and why it matters, in two or three sentences.",
+      "impact": "What improving it changes for the next developer or for correctness.",
+      "significance": 4,
+      "significanceReason": "The named defect or measured cost, in one or two sentences.",
+      "evidence": [
+        {
+          "path": "path/inside/the/repository.ts",
+          "lines": "120-148",
+          "quote": "A short verbatim excerpt from those lines."
+        }
+      ],
+      "proposedChange": "The change to make, concretely and without prescribing unrelated work.",
+      "files": ["path/inside/the/repository.ts"],
+      "acceptanceCriteria": [
+        "A statement that can be checked by reading the code or running the test suite."
+      ]
+    }
+  ],
+  "shortfall": "Why fewer than the requested count were delivered, or omit it when the count is met."
+}
+```
+
+Field rules:
+
+- `category` is exactly one of `clarity`, `structure`, `naming`, `tests`, `robustness`,
+  `correctness`.
+- `title` is one line, at most 200 characters, specific enough to be an issue title.
+- `summary`, `proposedChange`, and every `acceptanceCriteria` entry are non-empty.
+- `significance` is an integer from 1 through 5; `significanceReason` is non-empty and names the
+  impact at 4 or 5.
+- `evidence` has at least one entry. `path` is repository-relative with `/` separators, names an
+  existing regular file outside the excluded roots, and `lines` is `N` or `N-M` inside that
+  file's real line count. `quote` is optional and verbatim.
+- `files` is non-empty and every entry also appears in `evidence[].path`.
+- `recommendations` holds at most `requested` items.
+- `shortfall`, when present, is a non-empty sentence naming why the repository does not offer
+  more significant findings.
+
+A missing or out-of-range score, or a missing reason, rejects the whole answer and files nothing.
+Do not print the JSON as your answer; write it to the file and end the turn. If the repository
+affords no significant finding, write `{"recommendations": [], "shortfall": "…"}`.

package/public/favicon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Devboard">
+  <rect width="64" height="64" rx="14" fill="#1f6feb" />
+  <rect x="13" y="26" width="10" height="24" rx="3.5" fill="#ffffff" fill-opacity="0.72" />
+  <rect x="27" y="14" width="10" height="36" rx="3.5" fill="#ffffff" />
+  <rect x="41" y="20" width="10" height="30" rx="3.5" fill="#ffffff" fill-opacity="0.86" />
+</svg>