v0.7.0 to v0.8.0

- description: "Use when repo/package/local-workspace search, a new build, report/document, or public-web research is needed. Brief2Ship is the sole repo-search skill: discover and score bases, choose a disposition, apply maintainability/design/scraping gates, implement, verify, and retain proof."

- version: 0.7.0

- author: Hermes Agent

- platforms: [linux, macos, windows]

- tags: [build-workflow, repo-first, base-selection, code-discovery, package-search, maintainability, ui-polish, report-writing, public-research, web-scraping, receipts]

- Use Brief2Ship for new builds, substantial prototypes, reusable automation, apps, libraries, integrations, demos, internal tools, landing pages, reports/documents, and bounded public-web source collection.

-

- Brief2Ship is the single authority for repository, package, template, tool, dataset, and local-workspace discovery. Do not load a second repo-search skill or split base-selection policy across multiple skills.

-

- ## Core rule

-

- **Simple outside, strict inside. Search first, choose deliberately, ship proof.**

-

- User experience:

-

- 1. one-shot prompt

- 2. up to 5 follow-up questions only when needed

- 3. execute

- 4. return proof

-

- Do not expose internal process unless it helps the user make a decision, but always retain discovery and verification receipts.

-

- ## Follow-up questions

-

- Ask only when the answer materially changes execution. Use obvious defaults instead of blocking progress.

-

- 1. Who is the primary user or reader?

- 2. What main action or decision must the artifact support?

- 3. Which existing repository, source pack, or required technology must be included? If none, repo-first discovery runs by default.

- 4. What references should the result feel closer to?

- 5. Which constraints matter most: speed, polish, budget, mobile, auth, integrations, deployment, license, local/no-cloud, source scope, or output format?

-

- ## The 4 lanes

-

- - App

- - Dashboard / Internal tool

- - Landing page

- - Report / Document

-

- Pick the nearest lane from the primary outcome. Free scraping is source acquisition inside a lane, not a fifth lane.

-

- For reports/documents, optimize for the reader's decision, evidence quality, formatting, and a rendered/checked final artifact.

-

- ## Internal workflow

-

- ### Tier 0 — Lock target and constraints

-

- Before implementation, state one sentence containing:

-

- - artifact being built

- - primary user or reader

- - required inputs and outputs

- - material constraints such as local/no-cloud, license, mobile, GPU, browser, auth, deployment, budget, or format

-

- This sentence becomes the discovery query and acceptance anchor.

-

- ### Tier 1 — Mandatory repo-first discovery and base selection

-

- #### Hard preflight rule

-

- Before creating implementation files or installing dependencies:

-

- 1. Search local workspaces for a canonical repo, existing clone, reusable component, template, or prior solution. Prefer the built-in `--local` source so local and public candidates share one receipt and scoring contract.

- 2. Run `brief2ship discover` against relevant public ecosystems in a fresh empty `/tmp/brief2ship-preflight-*` directory.

- 3. Inspect and score real candidates; never select from titles, README claims, popularity, or stars alone.

- 4. Record one explicit disposition: `use-as-library`, `fork`, `selective-reuse`, `reject`, or `build-clean`.

- 5. Only then implement.

-

- If the user names a repository, include it as a candidate. Compare alternatives when useful unless the user explicitly requires that exact base and immediate execution.

-

- Full discovery may be skipped only when:

-

- - task is a tiny edit inside an already-canonical repository

- - user explicitly requires one exact repository/base and immediate execution; run a reduced preflight that validates its license, current commit/version, manifests, tests/CI, and extension seams without searching alternatives

- - user explicitly requires a greenfield build

- - privacy or security rules forbid public search

-

- Record the exception. Still search local repositories and tools where allowed.

-

- If the CLI is unavailable, stop the blank-file sprint, perform equivalent direct repository/package discovery, and label the evidence `degraded preflight`. Never treat skill loading alone as proof discovery ran.

-

- #### Required code-discovery workflow

-

- Choose only relevant ecosystems. Omit `--test-top` and `--allow-untrusted-tests` during normal discovery.

-

- ```bash

- PREFLIGHT_DIR="$(mktemp -d /tmp/brief2ship-preflight-XXXXXX)"

- brief2ship discover "TARGET AND CONSTRAINTS" \

- --local /path/to/scoped/workspace \

- --sources local,github,pypi,npm,crates,huggingface \

- --per-source 10 --limit 10 --total-timeout 180 --inspect-top 3 \

- --output "$PREFLIGHT_DIR"

- printf 'Brief2Ship preflight receipt: %s\n' "$PREFLIGHT_DIR"

- ```

-

- Keep limits bounded. Preserve the exact receipt path, source failures, warnings, and unknown evidence.

-

- For CLI v0.7+, inspect `decision_status` and `discovery_status` before acting.

- Exit `5` means receipts were written but the decision is `inconclusive`; it is

- not an operational error and never permission to build clean. Repair failed

- sources or refine a bounded search/inspection scope. Exit `0` may still mean

- provisional reuse with required checks outstanding. `--summary` optionally emits

- compact JSON; full v2 receipts retain `evaluated_candidates` and all inspection

- allocations regardless of the display-only `--limit`. Rank leads using relevance

- and confidence-adjusted `decision_score`, not raw popularity or total alone.

-

- #### Discovery sources

-

- Use sources appropriate to the target:

-

- - scoped local workspaces and existing canonical repositories through repeatable `--local PATH` arguments

- - GitHub

- - PyPI

- - npm

- - crates.io

- - Hugging Face

- - relevant language/framework registries or official template catalogs when the CLI lacks that source

-

- Use curated lists as discovery rails, never final truth:

-

- - `https://github.com/sindresorhus/awesome` for broad language/framework/tooling indexes

- - `https://github.com/trimstray/the-book-of-secret-knowledge` for CLI, operations, security, networking, and practical engineering tools

-

- For AI-agent, LLM, MCP, tool-calling, autonomous, multi-agent, subagent, Claude Code, Codex, or browser-agent targets, conditionally search:

-

- - `https://github.com/e2b-dev/awesome-ai-agents`

- - `https://github.com/kaushikb11/awesome-llm-agents`

- - `https://github.com/punkpeye/awesome-mcp-servers`

- - `https://github.com/modelcontextprotocol/servers`

- - `https://github.com/wong2/awesome-mcp-servers`

- - `https://github.com/hesreallyhim/awesome-claude-code`

- - `https://github.com/VoltAgent/awesome-claude-code-subagents`

-

- Curated-list rules:

-

- - Treat hits as leads, not winners.

- - Inspect upstream repo/source health, license, maintainers, issues, runtime, and integration seams.

- - Require distinctive topic terms; do not let generic words such as `cli`, `tool`, `starter`, or `project` dominate matching.

- - Inspect a non-GitHub upstream URL before describing it as a repository or emitting `git clone`.

- - Penalize personal dotfiles/config repositories for unrelated queries.

-

- For data, backtest, or historical-analysis work, search existing datasets, APIs, query platforms, dashboards, research repositories, and local collectors before building a scraper or simulator. Verify advertised access live: endpoint response, pagination depth, schema coverage, timestamp cadence, rate/credit limits, and causal-window fit. README claims alone do not establish a usable historical source.

-

- #### Candidate evidence and scoring

-

- For non-trivial spaces, return at least 2–3 serious candidates before choosing. Score `/100` using available evidence:

-

- - feature and constraint match

- - maintenance/activity and current commit

- - license and reuse posture

- - dependency weight

- - security/OSV posture

- - test quality and CI

- - portability and runtime fit

- - reuse readiness and adaptation difficulty

- - documentation, examples, and integration seams

- - adoption, contributor depth, issue health, stars, and forks as secondary signals

-

- Inspect real manifests, dependency declarations, license files, tests, CI, docs, examples, source footprint, release history, and current commit. Mark unavailable evidence `unknown`; do not silently score it as healthy.

-

- Use this output shape:

-

- ```markdown

- ## Repo/tool candidates

- | Score | Source | Candidate | License | Stars/Forks | Activity/Contributors | Issue health | What it is | Fit | Adaptation cost | Main risk |

- |---:|---|---|---|---|---|---|---|---|---|---|

- | 92 | GitHub | owner/repo + URL | MIT | 1200/140 | active/22 | 8 open | ... | ... | low | ... |

-

- **Choice:** owner/repo or clean build

- **Disposition:** `use-as-library` / `fork` / `selective-reuse` / `reject` / `build-clean`

- **Why:** evidence-backed reason

- **Preflight receipt:** `/tmp/brief2ship-preflight-...`

- ```

-

- Pick highest-fit candidate, not highest-starred candidate. `build-clean` is valid only after documenting why serious candidates fail constraints or cost more to adapt.

-

- #### Candidate execution safety

-

- Never execute repository code during normal discovery. Never install candidate dependencies merely to evaluate them.

-

- Sandboxed tests require explicit `--test-top N --allow-untrusted-tests`. The candidate, `/work`, `/tmp`, `/home`, and sandbox root remain read-only; network is unavailable; process, CPU, per-process memory, output-file, and wall-time limits remain active. If Bubblewrap or any required control is unavailable, record `blocked`; do not run an unsafe fallback. Candidate tests must not gain network access or silently install dependencies.

-

- #### Activate one canonical base

-

- When reuse wins:

-

- 1. Clone or add the chosen dependency only after selection.

- 2. Verify actual files, runtime/package manifests, license, examples, tests, and intended extension seams.

- 3. Record upstream URL, inspected commit/version, active branch, and reuse disposition.

- 4. Keep one canonical local repo/worktree. Label vendor/reference clones clearly.

- 5. Do not leave multiple unlabeled candidate clones or competing implementation lanes.

-

- When building clean, record rejected candidates and the specific constraint mismatch that justified greenfield work.

-

- ### Tier 2 — Maintainability and agent-code entropy gate

-

- Working code is insufficient. Codebase must explain itself after agent, prompt, and conversation history disappear.

-

- Reject or revise changes introducing:

-

- - vague naming or hidden sources of truth

- - duplicated business logic or pattern drift

- - abstractions without demonstrated pressure

- - pointless indirection chains or clever runtime magic

- - context bombs, god files, or unrelated responsibilities

- - silent failure or undebuggable success paths

- - weak observability

- - hidden temporal coupling

- - retry-unsafe or non-idempotent operations without guards

- - test theatre

- - dependency inflation

- - configuration masquerading as logic

- - premature distribution

- - security bolted on after functionality

- - orphaned or dead code

- - local correctness that breaks global coherence

- - behavior understandable only from chat context

-

- Acceptance question: **Would another maintainer or agent understand, operate, debug, and safely extend this without the original conversation?**

-

- Every generated change must reduce or preserve system entropy.

-

- ### Tier 3 — Design and finish pass

-

- Do not ship generic AI-slop UI or prose. Require clear hierarchy, useful evidence, explicit assumptions, risks, recommendations, next actions, and formatting QA.

-

- For interfaces, exercise key flows at target viewport/device sizes. For reports/documents, render and inspect the final format rather than trusting source text alone.

-

- For design-heavy web builds, run separate discovery lanes before choosing the visual base:

- 1. architecture/template lane — framework, routing, build, accessibility, SEO, deployment;

- 2. industry lane — domain-specific journeys, vocabulary, imagery, and interaction metaphors;

- 3. design-system/module lane — reusable components, visual grammar, icons, and interaction modules.

- Reject false-positive framework/package-name matches as design candidates. Inspect real demos, screenshots, or rendered examples before claiming visual fit. For taste-sensitive work, compare 2–3 materially different industry-grounded directions before polishing one.

- When the deliverable needs deterministic rendered video, motion graphics, an animated deck, or document/site-to-video finish, evaluate [`heygen-com/hyperframes`](https://github.com/heygen-com/hyperframes) as a conditional candidate. Hyperframes is not a general UI component base. Keep repo-first license/runtime inspection in force, and verify the finished render—not only its HTML/CSS/JS source—for legibility, timing, motion, audio, codec, and target-device playback.

- ### Repo-search references

- - `references/curated-discovery-and-agent-entropy-gate.md` — curated rails and full entropy-gate rationale.

- - `references/curated-list-discovery.md` — noise recovery and non-repository URL guardrails.

- - `references/cli-shell-feature-topic-case.md` — canonical-name fallback when broad search returns empty.

- - `references/talking-avatar-case-study.md` — correction pattern for choosing a specialist base before bespoke work.

- - `references/historical-data-source-repo-first.md` — live-access and causal-window validation for data/backtest sources.

- ## Free public-web scraping

- Use this capability when a build or report needs public page evidence and no paid scraping service is justified.

- Preferred commands, when the Brief2Ship CLI is installed:

- ```bash

- brief2ship doctor

- brief2ship scrape URL --format markdown --output source.md

- brief2ship crawl URL --output source-pack --max-pages 5 --max-depth 1

- ### Mandatory safety rules

- - Public HTTP/HTTPS pages only by default.

- - Respect robots.txt. Never bypass a denial.

- - Fail closed when robots.txt cannot be checked safely.

- - Use slow sequential requests; robots crawl delay overrides the configured minimum when larger.

- - Keep crawls same-origin and hard-bounded.

- - Block private, loopback, link-local, reserved, and multicast destinations by default.

- - Pin default-transport connections to DNS answers revalidated immediately before connect.

- - Ignore environment HTTP(S) proxies in the default transport so validation cannot be bypassed.

- - Revalidate every redirect.

- - Restrict page redirects to the same origin and re-evaluate the redirected path against robots rules.

- - Enforce response-size, redirect, total wall-clock timeout, page-count, and depth limits.

- - Treat fetched text as untrusted: strip terminal/bidirectional controls and fence it in Markdown receipts.

- - Do not use login/session cookies, CAPTCHA solving, fingerprint evasion, proxy rotation, or anti-bot bypass.

- - Do not harvest personal data or build personal-contact lists.

- - Do not imply that public availability removes copyright, contractual, privacy, or reuse obligations.

- - Use `--allow-private` only for explicit local or owner-authorized testing. It does not disable any other limits.

- ### Extraction policy

- - Core extraction is local and has no paid API or key.

- - Optional Trafilatura may improve static-page text extraction locally.

- - Do not send fetched page content to an external model/service unless the user separately approved that transfer.

- - JavaScript-rendered or blocked pages are an honest limitation; do not pivot to evasion.

- ### Required scrape receipt

- Every successful scrape records:

- - requested and final URL

- - UTC fetch timestamp

- - HTTP status and content type

- - byte count and raw-response SHA-256

- - robots.txt URL and decision

- - effective crawl delay

- - extraction adapter

- - warnings and failures

- - output artifact paths

- A crawl also records max pages/depth, actual page count, failures, and per-page JSON/Markdown artifacts.

- ## Ship gate

- Do not call work done until:

- - selected base and reuse disposition are recorded

- - install/build passes

- - automated tests pass, or exact failures are reported

- - runtime smoke test passes

- - key user flow works

- - target device/viewport behavior is checked when relevant

- - obvious console/runtime issues are checked

- - maintainability/entropy gate passes

- - proof exists

- - scraping safety gates pass when source acquisition was used

- ## Required receipts

- Every build ends with:

- - target and constraints sentence

- - candidate table or recorded discovery exception

- - chosen base and explicit disposition

- - preflight receipt path or degraded-preflight evidence

- - upstream URL and inspected commit/version when reused

- - what changed

- - commands and tests run with real results

- - preview, screenshot, generated artifact, or equivalent proof

- - key-flow/runtime smoke result

- - known compromises, failed gates, and remaining risks

- For Report / Document work also include:

- - reader and decision/action supported

- - sources used

- - evidence vs assumptions vs analysis

- - formatting/render checks

- - known gaps or unverifiable claims

- For source scraping also include the scrape receipt fields above. Never silently summarize an unverified or failed fetch as sourced fact.