diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..c4c41cb --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "brief2ship", + "description": "Official Brief2Ship plugin marketplace", + "owner": { + "name": "Michael Costea", + "url": "https://michaelcostea.com/" + }, + "plugins": [ + { + "name": "brief2ship", + "description": "Search and score existing code before greenfield AI builds, then ship with proof", + "version": "0.6.2", + "source": "./", + "author": { + "name": "Michael Costea", + "url": "https://michaelcostea.com/" + } + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..b2e4983 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "brief2ship", + "description": "Repo-first discovery and verified delivery for AI coding agents", + "version": "0.6.2", + "author": { + "name": "Michael Costea", + "url": "https://michaelcostea.com/" + }, + "homepage": "https://github.com/five0nit/brief2ship", + "repository": "https://github.com/five0nit/brief2ship", + "license": "MIT", + "keywords": [ + "agent-skills", + "ai-coding", + "code-search", + "package-search", + "repo-first", + "verified-delivery" + ] +} diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..2ab4869 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,65 @@ +name: Bug report +description: Report a reproducible Brief2Ship defect +title: "bug: " +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a defect. Remove credentials, private repository names, private URLs, personal data, and sensitive receipt content before posting. + - type: input + id: version + attributes: + label: Brief2Ship version + description: Output of `brief2ship --version`. + placeholder: brief2ship 0.6.2 + validations: + required: true + - type: dropdown + id: operating-system + attributes: + label: Operating system + options: + - Linux + - macOS + - Windows + - Other + validations: + required: true + - type: textarea + id: command + attributes: + label: Sanitized command + description: Preserve flags and structure, but replace private paths, URLs, tokens, and names. + render: shell + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: Include the exact error and a sanitized receipt excerpt when available. + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal reproduction + description: List deterministic steps using public or synthetic fixtures where possible. + validations: + required: true + - type: checkboxes + id: safety + attributes: + label: Safety check + options: + - label: I removed credentials, private URLs, private repository names, and personal data. + required: true + - label: I did not bypass robots.txt, authentication, CAPTCHA, or private-network protections. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..d1224b3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Questions and adoption stories + url: https://github.com/five0nit/brief2ship/discussions + about: Ask for help, share a receipt, or discuss an unbounded idea before opening an issue. + - name: Sensitive security report + url: https://github.com/five0nit/brief2ship/security/advisories/new + about: Report vulnerabilities privately. Do not open a public issue containing exploit details or secrets. diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 0000000..36a4229 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,56 @@ +name: Feature request +description: Propose a bounded improvement with a verifiable outcome +title: "feat: " +labels: ["enhancement", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Brief2Ship stays lean. Start with the problem and evidence, not a large proposed architecture. + - type: textarea + id: problem + attributes: + label: Problem + description: What repo-first decision, evidence gap, install path, or verification failure is difficult today? + validations: + required: true + - type: textarea + id: example + attributes: + label: Concrete example + description: Use public or synthetic data. Do not include credentials, private repository names, private URLs, or personal data. + validations: + required: true + - type: textarea + id: outcome + attributes: + label: Smallest useful outcome + description: Describe observable behavior, not implementation preference. + validations: + required: true + - type: textarea + id: acceptance + attributes: + label: Acceptance checks + placeholder: | + - deterministic fixture reproduces the gap + - behavior is bounded and cross-platform where claimed + - receipt explains the result + validations: + required: true + - type: dropdown + id: scope + attributes: + label: Area + options: + - Discovery provider + - Local workspace discovery + - Candidate inspection and scoring + - Agent Skill installation + - CLI usability + - Public-web collection + - Documentation and examples + - Release and packaging + - Other + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..db1d7f7 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,40 @@ +## Problem and scope + + + +## What changed + +- + +## Verification + + + +```text +command: +result: +``` + +## Reuse decision + +- [ ] `use-as-library` +- [ ] `fork` +- [ ] `selective-reuse` +- [ ] `reject` +- [ ] `build-clean` +- [ ] Canonical-repository exception; no new implementation base was required + +Reason: + +## Safety and maintainability + +- [ ] No credentials, private repository names, private URLs, or personal data entered the diff or receipts +- [ ] No candidate code executes during normal discovery +- [ ] Tests cover behavior changes or the PR explains why no new test is required +- [ ] Documentation and release surfaces were updated where relevant +- [ ] `python scripts/validate-release.py` passes +- [ ] `git diff --check` passes + +## Known gaps + +- diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml new file mode 100644 index 0000000..6ef0b41 --- /dev/null +++ b/.github/workflows/publish-pypi.yml @@ -0,0 +1,82 @@ +name: Publish to PyPI + +on: + workflow_dispatch: + +permissions: {} + +jobs: + verify: + name: Validate tag and release assets + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 + with: + python-version: '3.13' + cache: pip + - name: Validate source and release contract + run: python scripts/validate-release.py + - name: Require immutable release tag to match VERSION + id: names + env: + RELEASE_TAG: ${{ github.ref_name }} + RELEASE_REF_TYPE: ${{ github.ref_type }} + run: | + python -c "from pathlib import Path; import os; expected='v'+Path('VERSION').read_text(encoding='utf-8').strip(); actual=os.environ['RELEASE_TAG']; ref_type=os.environ['RELEASE_REF_TYPE']; assert ref_type == 'tag', ref_type; assert actual == expected, (actual, expected)" + VERSION="$(cat VERSION)" + echo "version=$VERSION" >> "$GITHUB_OUTPUT" + echo "wheel=brief2ship-$VERSION-py3-none-any.whl" >> "$GITHUB_OUTPUT" + echo "sdist=brief2ship-$VERSION.tar.gz" >> "$GITHUB_OUTPUT" + - name: Install distribution metadata checker + run: python -m pip install --upgrade pip twine + - name: Download and verify exact GitHub release assets + env: + GH_TOKEN: ${{ github.token }} + run: | + mkdir dist + gh release download "$GITHUB_REF_NAME" \ + --repo "$GITHUB_REPOSITORY" \ + --pattern '${{ steps.names.outputs.wheel }}' \ + --pattern '${{ steps.names.outputs.sdist }}' \ + --pattern 'SHA256SUMS' \ + --dir dist + python -m twine check \ + 'dist/${{ steps.names.outputs.wheel }}' \ + 'dist/${{ steps.names.outputs.sdist }}' + python scripts/verify-release-assets.py \ + --directory dist \ + --version '${{ steps.names.outputs.version }}' + - name: Preserve verified distributions for isolated publisher + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: python-distributions + path: | + dist/${{ steps.names.outputs.wheel }} + dist/${{ steps.names.outputs.sdist }} + if-no-files-found: error + retention-days: 1 + + publish: + name: Publish trusted distributions + needs: verify + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/p/brief2ship + permissions: + id-token: write + steps: + - name: Retrieve verified distributions + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 + with: + name: python-distributions + path: dist/ + - name: Publish through PyPI Trusted Publishing + uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1 + with: + packages-dir: dist/ + skip-existing: false + verbose: true diff --git a/CHANGELOG.md b/CHANGELOG.md index 86bd921..5b3713b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 0.6.2 - 2026-09-05 + +- reposition Brief2Ship around its sharpest searchable job: stop AI coding agents rebuilding what already exists +- move a runnable PyPI quickstart, real dogfood demo, scored result, comparison table, and proof strip above the detailed workflow documentation +- add a custom 1280×640 social preview, an animated terminal receipt, and three evidence-bounded decision cases +- add GitHub CLI Agent Skills, skills.sh, Claude Code plugin, PyPI, and immutable-tag installation routes +- add GitHub Trusted Publishing workflow for PyPI with exact release-tag/version validation and no repository secret requirement +- add Code of Conduct, issue forms, pull-request template, roadmap, contribution links, and Discussions routes +- expand package metadata and release-contract checks for distribution, community, and marketing artifacts + ## 0.6.1 - 2026-09-04 - restore HTTPS scraping on Python 3.12 and 3.13 by forwarding the portable `SSLContext` argument without the removed `HTTPSConnection(check_hostname=...)` keyword diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..cfc8fd2 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,73 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment include: + +- demonstrating empathy and kindness toward other people; +- being respectful of differing opinions, viewpoints, and experiences; +- giving and gracefully accepting constructive feedback; +- accepting responsibility, apologizing to those affected by mistakes, and learning from the experience; +- focusing on what is best for the overall community. + +Examples of unacceptable behavior include: + +- sexualized language or imagery, and sexual attention or advances of any kind; +- trolling, insulting or derogatory comments, and personal or political attacks; +- public or private harassment; +- publishing another person's private information without explicit permission; +- other conduct that could reasonably be considered inappropriate in a professional setting. + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing these standards and will take appropriate and fair corrective action in response to behavior they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct. Reasons for moderation decisions will be communicated when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces and when an individual officially represents the community in public spaces. + +## Enforcement + +Report abusive, harassing, or otherwise unacceptable behavior privately to the maintainer through the contact route on the [`five0nit` GitHub profile](https://github.com/five0nit). Do not place sensitive personal information in a public issue. All complaints will be reviewed promptly and fairly, with respect for the privacy and security of the reporter. + +## Enforcement Guidelines + +Community leaders will use these Community Impact Guidelines when determining consequences. + +### 1. Correction + +**Community Impact:** Inappropriate language or other behavior deemed unprofessional or unwelcome. + +**Consequence:** A private written warning explaining the violation and why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact:** A violation through a single incident or series of actions. + +**Consequence:** A warning with consequences for continued behavior. Interaction with the people involved, including unsolicited contact with those enforcing the Code of Conduct, may be prohibited for a specified period. + +### 3. Temporary Ban + +**Community Impact:** A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence:** A temporary ban from interaction or public communication with the community for a specified period. + +### 4. Permanent Ban + +**Community Impact:** A pattern of violating community standards, including sustained harassment, aggression, or disparagement of classes of individuals. + +**Consequence:** A permanent ban from public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at . + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). diff --git a/MANIFEST.in b/MANIFEST.in index f123fde..b5b280e 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -3,11 +3,15 @@ include LICENSE include README.md include CHANGELOG.md include CONTRIBUTING.md +include CODE_OF_CONDUCT.md include SECURITY.md +include ROADMAP.md include docs/*.md +recursive-include docs/assets *.gif *.png *.svg *.txt recursive-include docs/plans *.md recursive-include skills *.md recursive-include templates *.md recursive-include scripts *.py recursive-include tests *.py -recursive-include .github *.yml +recursive-include .github *.md *.yml +recursive-include .claude-plugin *.json diff --git a/README.md b/README.md index ab1b49f..863915a 100644 --- a/README.md +++ b/README.md @@ -1,181 +1,177 @@ # Brief2Ship -**One brief. Better build. Proof included.** +**Stop AI coding agents from rebuilding what already exists.** -Brief2Ship is a lean operating standard and local CLI for AI-assisted product work. It searches local workspaces, repositories, packages, tools, templates, and datasets before greenfield work, scores reuse evidence, collects public-web sources, and turns a strong brief into a shipped, verified artifact. +[![CI](https://github.com/five0nit/brief2ship/actions/workflows/ci.yml/badge.svg)](https://github.com/five0nit/brief2ship/actions/workflows/ci.yml) +[![PyPI](https://img.shields.io/pypi/v/brief2ship?label=PyPI)](https://pypi.org/project/brief2ship/) +[![Python](https://img.shields.io/pypi/pyversions/brief2ship)](https://pypi.org/project/brief2ship/) +[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-open%20standard-6CFFB3)](https://agentskills.io/) +[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![GitHub stars](https://img.shields.io/github/stars/five0nit/brief2ship?style=social)](https://github.com/five0nit/brief2ship/stargazers) -## What it is +Brief2Ship is a dependency-free Python CLI and portable Agent Skill for **repo-first discovery**. It searches local code plus GitHub, PyPI, npm, crates.io, and Hugging Face; inspects and scores real candidates; recommends reuse or a clean build; and finishes work with evidence instead of vibes. -Brief2Ship is a **workflow standard**, not a giant framework. +![Terminal demo showing Brief2Ship selecting the local repository for reuse after evidence scoring](https://raw.githubusercontent.com/five0nit/brief2ship/v0.6.2/docs/assets/brief2ship-demo.gif) -It helps an operator or agent: +*Real dogfood receipt: `local/brief2ship`, 70.50/100, inspected, `selective-reuse`. [Read the source transcript](https://github.com/five0nit/brief2ship/blob/v0.6.2/docs/assets/demo-transcript.txt) or [see more decision cases](https://github.com/five0nit/brief2ship/blob/v0.6.2/docs/case-studies.md).* -1. **Get a strong one-shot prompt** -2. **Choose a base before building greenfield** -3. **Reject brittle unreadable agent code** -4. **Search, inspect, and score existing local and public code** -5. **Collect public evidence with safe free scraping when needed** -6. **Format reports and documents for decision-ready reading** -7. **Turn the work into a verified artifact with receipts** +## 30-second quickstart -The public repository is the canonical source. Installed skills and CLI environments are local projections and should be reproducible from a tagged release. +Run directly from PyPI without a permanent install: -### One repo-search skill - -Brief2Ship is the sole skill for repository, package, template, dataset, and local-workspace discovery. Base-selection policy, maintainability/entropy checks, implementation gates, and proof receipts live here rather than in a second overlapping search skill. - -## User experience - -1. One-shot prompt -2. Up to 5 follow-up questions only when needed -3. Execute -4. Return proof - -The user should not have to learn the internals. +```bash +uvx brief2ship discover "local robots-aware web scraper" \ + --sources github,pypi,npm,crates,huggingface \ + --limit 5 --inspect-top 2 \ + --output discovery/ +``` -## Internal workflow +Add a bounded local workspace to the same comparison: -The operating model stays simple: one strong brief, three internal tiers, and a final proof gate. +```bash +uvx brief2ship discover "local robots-aware web scraper" \ + --local /path/to/scoped/workspace \ + --sources local,github,pypi,npm,crates,huggingface \ + --per-source 10 --limit 10 --inspect-top 3 \ + --total-timeout 180 \ + --output discovery/ +``` -### Tier 1 — Repo-first +Brief2Ship writes both human-readable and machine-readable receipts: -Search for the best existing repository, starter, tool, or template before building. +```text +discovery/ +├── discovery.md +├── discovery.json +└── worktrees/ # bounded inspection clones when required +``` -Use the built-in `brief2ship discover` command for both local and public candidates. +The result records one explicit disposition: -### Tier 2 — Maintainability gate +- `use-as-library` +- `fork` +- `selective-reuse` +- `reject` +- `build-clean` -Use [`droogans/unmaintainable-code`](https://github.com/droogans/unmaintainable-code) in reverse. +Repository code is **never executed during normal discovery**. Explicit candidate tests require both `--test-top` and `--allow-untrusted-tests`; they run only in the supported Linux Bubblewrap sandbox with **no network** access, a cleared environment, read-only filesystems, and resource limits. -Reject vague naming, hidden logic, duplicated business logic, unjustified abstraction, weak observability, dependency bloat, and chat-context-only code. +## Why Brief2Ship? -### Tier 3 — Design / UI / document finish +Most coding agents start generating code as soon as they understand the request. Brief2Ship inserts one high-value decision first: -Do not ship generic AI-slop UI or prose. Preserve hierarchy, evidence, accessibility, legibility, and restrained motion. +> **Does a suitable implementation, package, template, tool, dataset, or local project already exist?** -Useful references: +| Approach | Primary job | What Brief2Ship adds | +|---|---|---| +| AI coding agent | Generate or modify code | Mandatory pre-build search, evidence scoring, and a reuse decision | +| Spec-driven toolkit | Define what should be built | Selection of the best existing base before implementation | +| GitHub/code search | Return search results | Registry + local search, bounded inspection, deterministic scoring, and hard blockers | +| Starter or boilerplate | Provide one starting point | Comparison against alternatives instead of defaulting to the first template | +| Generic scraper | Fetch pages | Public-target, robots, redirect, DNS, size, and provenance controls | -- [`shadcn-ui/ui`](https://github.com/shadcn-ui/ui) -- [`tailwindlabs/headlessui`](https://github.com/tailwindlabs/headlessui) -- [`motiondivision/motion`](https://github.com/motiondivision/motion) -- [`darkroomengineering/lenis`](https://github.com/darkroomengineering/lenis) only when justified -- [`magicuidesign/magicui`](https://github.com/magicuidesign/magicui) selectively -- [`heygen-com/hyperframes`](https://github.com/heygen-com/hyperframes) when the deliverable needs deterministic HTML/CSS/JS-rendered video, motion graphics, an animated deck, or document/site-to-video finish; inspect the rendered output, not only the source HTML +Brief2Ship is a **workflow standard**, not a giant framework. It preserves operator judgment and makes unknown evidence visible rather than pretending every candidate is safe or suitable. -## The 4 default lanes +## What gets scored -Brief2Ship ships with four default lanes: +Candidates receive deterministic `/100` evidence-backed scores: -1. **App** -2. **Dashboard / Internal tool** -3. **Landing page** -4. **Report / Document** +| Component | Weight | +|---|---:| +| Feature and constraint match | 25 | +| Maintenance and activity | 15 | +| Dependency weight | 10 | +| Security posture and OSV findings | 15 | +| Test quality and CI | 10 | +| Portability | 10 | +| Reuse readiness and adaptation cost | 10 | +| Adoption, contributors, forks, watchers, and issue health | 5 | -Free scraping is a source-acquisition capability inside these lanes, especially Report / Document. It is not a fifth lane. +Brief2Ship inspects manifests, dependency declarations, licenses, tests, CI, docs, examples, source footprint, release activity, contributors, watchers, forks, issue health, and homepage evidence. Missing evidence stays `unknown`; popularity never overrides fit, licensing, security, or maintainability. -See [docs/lanes.md](docs/lanes.md), [docs/report-document-lane.md](docs/report-document-lane.md), and [docs/free-scraping.md](docs/free-scraping.md). +## Install the CLI -## Code and solution discovery +### PyPI -Brief2Ship v0.6 searches scoped local workspaces plus five free public ecosystems before new code is written: +Persistent tool install: ```bash -brief2ship discover "local web scraper with robots support" \ - --local /path/to/scoped/workspace \ - --sources local,github,pypi,npm,crates,huggingface \ - --per-source 10 \ - --limit 10 \ - --total-timeout 180 \ - --inspect-top 3 \ - --output discovery/ +uv tool install brief2ship +brief2ship doctor ``` -Candidates receive deterministic evidence-backed scores for: +One-off execution: -- feature match — `/25` -- maintenance/activity — `/15` -- dependency weight — `/10` -- security posture and OSV findings — `/15` -- test quality — `/10` -- portability — `/10` -- reuse readiness/difficulty — `/10` -- adoption/contributor/issue health — `/5` +```bash +uvx brief2ship --version +``` -The result recommends `fork`, `use-as-library`, `selective-reuse`, `reject`, or `build-clean`. Canonical GitHub URLs are deduplicated across registries and matching local clones, and any merged candidate retaining a validated local path is inspected locally regardless of primary package source. A zero-result long-form GitHub query gets one deterministic three-term fallback, recorded in the receipt. `--inspect-top` allocates scarce inspection slots by direct feature fit, statically inspects local projects in place, hydrates public repository metadata including contributors, real watchers, true issue-only counts, and homepage evidence, performs bounded shallow clones when needed, and checks real manifests, dependencies, licenses, tests, CI, documentation, examples, languages, and source footprint before reranking. +With optional local Trafilatura extraction: -Repository code is never executed by default. Explicit tests require `--test-top N --allow-untrusted-tests` and a Linux Bubblewrap sandbox. The sandbox clears the environment, runs with no network access, hides the host home, makes the entire filesystem read-only, and limits additional processes, CPU, per-process memory, output-file size, and wall time. Unsupported systems produce a blocked receipt—never an unsafe fallback. +```bash +uv tool install --with 'trafilatura>=2.1,<3' brief2ship +``` -See [docs/code-discovery.md](docs/code-discovery.md). Current Linux/Windows tests, local artifacts, clean installs, live provider smoke, and bounded real-candidate inspection are recorded in the source-checkout receipt at `docs/releases/v0.6.1-single-search-skill-receipt.md`. Release receipts remain outside built packages so their artifact hashes cannot become self-referential. +### Immutable GitHub tag -## Free scraping +```bash +uv tool install git+https://github.com/five0nit/brief2ship.git@v0.6.2 +brief2ship doctor +``` -Brief2Ship includes local, zero-paid-API source collection: +### Local development ```bash -brief2ship scrape https://example.com/article --format markdown --output article.md -brief2ship crawl https://example.com/docs --output research-pack --max-pages 5 --max-depth 1 +git clone https://github.com/five0nit/brief2ship.git +cd brief2ship +python3 -m venv .venv +.venv/bin/python -m pip install -e '.[dev]' +.venv/bin/brief2ship doctor ``` -Built-in rules: +On Windows PowerShell, use `.venv\Scripts\python.exe` and `.venv\Scripts\brief2ship.exe`. -- HTTP/HTTPS public pages only -- robots.txt required and fail-closed when unavailable -- private, loopback, link-local, reserved, and multicast targets blocked by default -- each default-transport connection is pinned to DNS answers revalidated immediately before connect -- environment HTTP(S) proxies are ignored so they cannot bypass target validation -- every redirect revalidated -- page redirects restricted to the same origin and rechecked against robots rules -- same-origin sequential crawl only -- default 1-second minimum delay; robots crawl delay wins when larger -- 2 MB/page default response cap -- one total wall-clock timeout across connect, redirects, and body streaming -- 5-page/depth-1 crawl default; hard cap 20 pages/depth 3 -- no cookies, login automation, CAPTCHA bypass, fingerprint evasion, or proxy rotation -- JSON/Markdown receipts include final URL, fetch time, SHA-256, extractor, robots status, and warnings -- untrusted page text is control-stripped and fenced as inert code in Markdown receipts +## Install the Agent Skill -`--allow-private` exists only for explicit local or owner-authorized testing. It does not disable robots, timeouts, response limits, redirect limits, or crawl caps. +Brief2Ship follows the open [Agent Skills specification](https://agentskills.io/) and can be discovered from its `skills/brief2ship/SKILL.md` directory. -The core extractor has no runtime dependency. Optional [Trafilatura](https://github.com/adbar/trafilatura) improves static-page extraction locally; page content is never sent to a model or scraping service. +### GitHub CLI -## Install the CLI +GitHub CLI 2.90 or newer can install the tagged skill for supported agent hosts: -### Using `uv` +```bash +gh skill install five0nit/brief2ship brief2ship@v0.6.2 +``` -From a release tag: +Example host-specific installation: ```bash -uv tool install git+https://github.com/five0nit/brief2ship.git@v0.6.1 -brief2ship doctor +gh skill install five0nit/brief2ship brief2ship@v0.6.2 \ + --agent claude-code --scope user ``` -With optional Trafilatura extraction: +### skills.sh-compatible agents ```bash -uv tool install --with 'trafilatura>=2.1,<3' git+https://github.com/five0nit/brief2ship.git@v0.6.1 -brief2ship doctor +npx skills add five0nit/brief2ship --skill brief2ship ``` -### Local development install +### Claude Code plugin + +The repository also carries a native Claude Code plugin manifest: ```bash -git clone https://github.com/five0nit/brief2ship.git -cd brief2ship -python3 -m venv .venv -.venv/bin/python -m pip install -e . -.venv/bin/brief2ship doctor -.venv/bin/python -m brief2ship --version +claude plugin marketplace add five0nit/brief2ship +claude plugin install brief2ship@brief2ship ``` -On Windows PowerShell, use `.venv\Scripts\python.exe` and `.venv\Scripts\brief2ship.exe`. - -## Install the Hermes skill +### Hermes Agent Default profile: ```bash hermes skills install \ - https://raw.githubusercontent.com/five0nit/brief2ship/v0.6.1/skills/brief2ship/SKILL.md \ + https://raw.githubusercontent.com/five0nit/brief2ship/v0.6.2/skills/brief2ship/SKILL.md \ --category software-development \ --yes ``` @@ -185,79 +181,108 @@ Named profile: ```bash hermes profile create qa --no-alias --no-skills hermes --profile qa skills install \ - https://raw.githubusercontent.com/five0nit/brief2ship/v0.6.1/skills/brief2ship/SKILL.md \ + https://raw.githubusercontent.com/five0nit/brief2ship/v0.6.2/skills/brief2ship/SKILL.md \ --category software-development \ --yes hermes --profile qa skills list ``` -Load with `/skill brief2ship` in chat or `hermes --skills brief2ship` at startup. +Tagged skill URLs are immutable. Upgrade by installing the next tag explicitly with `--force --yes`. -Tagged skill URLs are immutable. To upgrade, install the next tag URL explicitly with `--force --yes`. `hermes skills uninstall brief2ship` removes the selected profile's copy after confirmation. +## One repo-search skill -## Repository contents +Brief2Ship keeps repository, package, template, dataset, tool, and local-workspace discovery in one place. Base selection, maintainability checks, implementation gates, and proof receipts do not drift across overlapping skills. -- `src/brief2ship/` — zero-dependency local/public discovery, scraping, and crawl CLI -- `skills/brief2ship/SKILL.md` — the sole Hermes repo-search/build-delivery skill -- `skills/brief2ship/references/` — absorbed curated, entropy, canonical-name, avatar, and historical-data guidance -- `docs/how-it-works.md` — workflow breakdown -- `docs/lanes.md` — the 4 default lanes -- `docs/free-scraping.md` — safety, commands, limits, and receipts -- `docs/code-discovery.md` — providers, scoring, inspection, sandboxing, and receipts -- `docs/examples.md` — prompts and execution patterns -- `templates/` — kickoff, report, scrape, and build receipt templates -- `tests/` — unit and local integration tests -- `scripts/validate-release.py` — release contract gate +The workflow stays simple outside and strict inside: + +1. **Brief** — lock the target, user, inputs, outputs, and constraints. +2. **Search** — inspect local workspaces and relevant public ecosystems. +3. **Score** — compare fit, health, license, security, tests, and reuse cost. +4. **Decide** — record one reuse/build disposition before implementation. +5. **Ship** — verify the artifact and retain proof. + +## Internal delivery gates + +### Tier 1 — Repo-first -## Lightweight receipts +Search before greenfield work. Use the built-in `brief2ship discover` command for local and public candidates. -Every build should end with: +### Tier 2 — Maintainability -- chosen base and why -- changed files -- commands/tests run -- verification/proof -- known compromises +Reject vague naming, hidden logic, duplicated business rules, unjustified abstraction, weak observability, dependency bloat, retry-unsafe operations, test theatre, and code understandable only from chat history. -Every scrape adds source URL, final URL, timestamp, raw response hash, robots decision, extractor, byte count, and warnings. +### Tier 3 — Finish -Every discovery run adds provider status, rate-limit evidence, normalized candidate identity, component scores, evidence coverage, unknown cost, hard blockers, repository inspection, OSV results, sandbox receipts, recommendation status, and limitations. +Do not ship generic AI-slop UI or prose. Preserve hierarchy, evidence, accessibility, legibility, and restrained motion. For deterministic rendered video, motion graphics, animated decks, or document/site-to-video work, [`heygen-com/hyperframes`](https://github.com/heygen-com/hyperframes) is a conditional reference—not a general UI component base. -Use [templates/build-receipt-template.md](templates/build-receipt-template.md) and [templates/scrape-receipt-template.md](templates/scrape-receipt-template.md). +## The 4 default lanes -## Non-goals +1. **App** +2. **Dashboard / Internal tool** +3. **Landing page** +4. **Report / Document** -Brief2Ship is not: +Free public-web collection is source acquisition inside a lane, especially Report / Document. It is not a fifth lane. -- a full app framework -- a replacement for product judgment -- a generic enterprise scoring platform -- a mandatory design system -- a rigid project-management workflow -- a browser-fingerprint or anti-bot evasion product -- an authenticated-session scraper -- an unbounded distributed crawler +See [docs/lanes.md](docs/lanes.md), [docs/report-document-lane.md](docs/report-document-lane.md), and [docs/examples.md](docs/examples.md). -The goal is better delivery and evidence without harming judgment, accuracy, websites, or users. +## Safe public research -## Development +Brief2Ship also provides local, zero-paid-API source collection: ```bash -PYTHONPATH=src python3 -m unittest discover -s tests -v -python3 scripts/validate-docs.py -python3 scripts/validate-release.py -python3 -m build +brief2ship scrape https://example.com/article --format markdown --output article.md +brief2ship crawl https://example.com/docs --output research-pack --max-pages 5 --max-depth 1 ``` -See [CONTRIBUTING.md](CONTRIBUTING.md). +Core rules include: + +- robots.txt required and fail-closed when it cannot be checked safely; +- public HTTP/HTTPS targets only by default; +- private, loopback, link-local, reserved, and multicast destinations blocked; +- DNS answers revalidated and pinned immediately before connection; +- environment HTTP(S) proxies ignored by the default transport; +- every redirect revalidated and page redirects restricted to same-origin; +- sequential crawling with hard page, depth, byte, redirect, and wall-clock limits; +- no cookies, login automation, CAPTCHA bypass, fingerprint evasion, proxy rotation, or personal-data harvesting; +- JSON/Markdown receipts with final URL, fetch time, SHA-256, robots decision, extractor, bytes, warnings, and failures. + +See [docs/free-scraping.md](docs/free-scraping.md) and [docs/code-discovery.md](docs/code-discovery.md). + +## Proof and trust + +The v0.6.1 compatibility release passed: + +- 141 tests on Python 3.11, 3.12, and 3.13; +- seven Linux/Windows GitHub Actions jobs; +- Ruff critical selectors; +- Pyright with 0 errors and 0 warnings; +- clean wheel and extracted-sdist tests; +- live HTTPS positive and hostname-mismatch negative controls. + +Current source-checkout evidence is retained at `docs/releases/v0.6.2-discoverability-receipt.md`. Release receipts remain outside built packages so their artifact hashes cannot become self-referential. Historical v0.6.1 evidence remains at `docs/releases/v0.6.1-single-search-skill-receipt.md`. + +## Repository map + +- `src/brief2ship/` — dependency-free CLI implementation +- `skills/brief2ship/SKILL.md` — portable repo-first Agent Skill +- `docs/case-studies.md` — real decision examples +- `docs/code-discovery.md` — providers, scoring, inspection, and sandboxing +- `docs/free-scraping.md` — network safety and receipt contract +- `docs/examples.md` — prompts and execution patterns +- `templates/` — kickoff, report, scrape, and build receipt templates +- `tests/` — unit, integration, security, and release-contract tests +- `scripts/verify-release-assets.py` — exact wheel/sdist/checksum gate used before PyPI publication +- `ROADMAP.md` — bounded public roadmap + +## Community -## Contributors +Questions and adoption stories belong in [Discussions](https://github.com/five0nit/brief2ship/discussions). Reproducible defects and scoped improvements belong in [Issues](https://github.com/five0nit/brief2ship/issues). -Initial framework direction and product requirements: **Mike** -Packaging, workflow codification, and repository implementation: **Hermes Agent** +Read [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), [SECURITY.md](SECURITY.md), and [ROADMAP.md](ROADMAP.md) before contributing. -Future contributions should keep Brief2Ship lean. If a feature makes the workflow harder to apply safely and consistently, it probably does not belong. +If Brief2Ship stops your agent reinventing one dependency, **[star the repository](https://github.com/five0nit/brief2ship)** so another builder can find it. ## License -MIT for Brief2Ship. Upstream referenced projects retain their own licenses. +MIT for Brief2Ship. Upstream projects retain their own licenses. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..5f56c0a --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,39 @@ +# Brief2Ship roadmap + +Brief2Ship stays deliberately lean. Roadmap items must improve repo-first decisions, portable installation, evidence quality, or verified delivery without turning the project into a general-purpose agent framework. + +## Now — v0.6.x distribution and adoption + +- publish signed, tagged Python distributions to PyPI through GitHub Trusted Publishing; +- validate and publish `skills/brief2ship` through GitHub's Agent Skills workflow; +- test documented installation on GitHub Copilot, Claude Code, Codex, Cursor, Gemini CLI, and Hermes before claiming compatibility; +- improve first-run examples, error messages, and receipt readability; +- publish small, reproducible decision cases rather than unsupported savings claims. + +## Next — v0.7 evidence quality + +- normalize common package-license metadata without weakening hard blockers; +- improve multi-query recall while keeping provider limits deterministic; +- make inspection-budget allocation easier to explain from receipts; +- add fixture-backed examples for local/public deduplication and partial provider failure; +- expose concise summary output without removing the full Markdown/JSON receipt. + +## Later — only with demonstrated demand + +- optional CI check for repository-owned Brief2Ship policy; +- portable adapters where an agent host cannot consume the open Agent Skills format directly; +- signed provenance for published release artifacts; +- additional registries only when a maintained public API and bounded threat model exist. + +## Non-goals + +- becoming a full coding agent or project-management platform; +- executing candidate repositories during ordinary discovery; +- paid-service requirements in the core flow; +- unbounded crawling, authenticated scraping, CAPTCHA bypass, or stealth automation; +- ranking by stars alone; +- adding integrations before their install and verification paths are tested. + +## Contributing to the roadmap + +Use [GitHub Discussions](https://github.com/five0nit/brief2ship/discussions) for problem statements and adoption stories. Open an issue only when the desired outcome and acceptance checks are bounded enough to implement. diff --git a/VERSION b/VERSION index ee6cdce..b616048 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.6.1 +0.6.2 diff --git a/docs/assets/brief2ship-demo.gif b/docs/assets/brief2ship-demo.gif new file mode 100644 index 0000000..a1278a7 Binary files /dev/null and b/docs/assets/brief2ship-demo.gif differ diff --git a/docs/assets/demo-transcript.txt b/docs/assets/demo-transcript.txt new file mode 100644 index 0000000..b7fca10 --- /dev/null +++ b/docs/assets/demo-transcript.txt @@ -0,0 +1,17 @@ +Brief2Ship terminal demo source + +The embedded README GIF is a deterministic visualisation of the public v0.6.0 dogfood receipt at docs/releases/v0.6.0-single-search-skill-receipt.md. + +Command: + brief2ship discover "brief2ship repository search" --local /workspace --sources local,github,pypi,npm,crates,huggingface --output discovery/ + +Verified result reproduced in the animation: + candidate: local/brief2ship + score: 70.50/100 + feature match: 11.00/25 + inspection: inspected + disposition: selective-reuse + status: provisional + overall: selective-reuse + +The animation wraps the command and translates the `selective-reuse` disposition to the plain-language line `Reuse selected components` for phone-size legibility. It preserves the provisional status and does not claim a benchmark or a new run. diff --git a/docs/assets/social-preview.png b/docs/assets/social-preview.png new file mode 100644 index 0000000..7fe0c44 Binary files /dev/null and b/docs/assets/social-preview.png differ diff --git a/docs/assets/social-preview.svg b/docs/assets/social-preview.svg new file mode 100644 index 0000000..cdd261b --- /dev/null +++ b/docs/assets/social-preview.svg @@ -0,0 +1,62 @@ + + Brief2Ship social preview + Stop AI agents rebuilding what already exists. Search, score, reuse, and ship proof. + + + + + + + + + + + + B2S + BRIEF + 2 + SHIP + REPO-FIRST DISCOVERY FOR AI CODING AGENTS + + Stop AI agents + rebuilding what + already exists. + Search six sources. Score evidence. + Reuse deliberately. Ship proof. + + + + + + + + + repository discovery receipt + + + $ + brief2ship discover + "brief2ship repository search" + + SEARCH + local + 5 public sources + BEST MATCH + local/brief2ship + SCORE + 70.50 / 100 + + SELECTIVE-REUSE + + + + + SEARCH + → + SCORE + → + REUSE OR BUILD CLEAN + → + PROOF + OPEN SOURCE · MIT · ZERO CORE DEPS + + diff --git a/docs/case-studies.md b/docs/case-studies.md new file mode 100644 index 0000000..4760875 --- /dev/null +++ b/docs/case-studies.md @@ -0,0 +1,78 @@ +# Brief2Ship decision cases + +These cases show the decision Brief2Ship is designed to improve. They are not performance benchmarks, invented savings claims, or guarantees that the highest-scoring candidate should always be reused. + +## 1. Dogfooding found the canonical local project + +**Need:** verify that local-workspace discovery could find and inspect Brief2Ship inside a larger workspace. + +**Search:** `brief2ship repository search` with the local source enabled. + +**Observed result:** + +```text +candidate: local/brief2ship +score: 70.50/100 +feature match: 11.00/25 +inspection: inspected +disposition: selective-reuse +status: provisional +overall: selective-reuse +``` + +**Decision:** `selective-reuse` the existing canonical repository rather than create another implementation. + +**What the receipt exposed:** an earlier depth-first scanner could let a broad directory starve sibling projects under the traversal cap. A deterministic regression reproduced the problem, traversal changed to breadth-first, and the successful dogfood run was repeated. + +**Proof:** source-checkout receipt `docs/releases/v0.6.0-single-search-skill-receipt.md`, section “Dogfood proof.” Release receipts stay outside built packages to avoid self-referential artifact hashes. + +## 2. A specialist avatar base beat a custom first attempt + +**Need:** build a 3D rigged talking avatar with morph targets and visemes. + +**Initial failure:** implementation began with a custom mouth-overlay/2D cutout before repository comparison. + +**Candidate review:** + +| Score | Candidate | Evidence-backed fit | +|---:|---|---| +| 88 | [`met4citizen/TalkingHead`](https://github.com/met4citizen/TalkingHead) | MIT; direct 3D talking-avatar and lip-sync fit | +| 75 | `lexziconAI/TalkingHead` | Related fork/copy with lower confidence | + +**Decision:** use the specialist 3D base for a deterministic bundled-GLB proof before adapting a branded avatar. + +**Boundary:** a flat puppet or arbitrary uploaded image is a different problem class. Reusing a high-scoring repository does not remove asset-format constraints. + +**Proof:** [`skills/brief2ship/references/talking-avatar-case-study.md`](../skills/brief2ship/references/talking-avatar-case-study.md). + +## 3. Search can correctly end in `build-clean` + +**Need:** find a Python robots-aware scraper with strict public-target safety. + +**Live bounded run:** local workspace, GitHub, PyPI, npm, crates.io, and Hugging Face were queried; 13 provider results were observed and the final shortlist contained four candidates. + +| Score | Candidate | Source | Decision | +|---:|---|---|---| +| 62.50 | `ts-web-scraper` | npm | `build-clean` | +| 55.39 | `mcp-scraper` | npm | `build-clean` | +| 54.50 | `@the-convocation/twitter-scraper` | npm | `build-clean` | +| 51.77 | `web-scraper-python-library` | PyPI | `reject` | + +**Decision:** `build-clean` because no candidate cleared the reuse gates. The top candidate was recent and light, but the observed evidence did not establish the required Python and network-safety fit. + +**Why this matters:** repo-first does not mean “force reuse.” It means search, inspect, make unknowns visible, and justify greenfield work when adaptation would cost more or violate constraints. + +**Receipt note:** this run was executed on 2026-09-04 UTC with Brief2Ship v0.6.1. Public metadata can change; the table is an observed decision receipt, not a current endorsement of any package. + +## Reproduce the decision shape + +```bash +brief2ship discover "TARGET AND CONSTRAINTS" \ + --local /path/to/scoped/workspace \ + --sources local,github,pypi,npm,crates,huggingface \ + --per-source 10 --limit 10 --inspect-top 3 \ + --total-timeout 180 \ + --output discovery/ +``` + +Read `discovery.md` for the human decision and retain `discovery.json` for machine-readable evidence. diff --git a/docs/releases/v0.6.2-discoverability-receipt.md b/docs/releases/v0.6.2-discoverability-receipt.md new file mode 100644 index 0000000..87e85b1 --- /dev/null +++ b/docs/releases/v0.6.2-discoverability-receipt.md @@ -0,0 +1,136 @@ +# Brief2Ship v0.6.2 Discoverability Release Receipt + +**Status:** Release candidate — local verification passed; remote gates pending +**Release date:** 2026-09-05 AEST +**Repository:** `five0nit/brief2ship` +**Planned tag:** `v0.6.2` + +## Target + +Make Brief2Ship discoverable as the repo-first discovery CLI and Agent Skill that stops AI coding agents rebuilding what already exists, while preserving its dependency-free core, safety controls, maintainability gate, and verification receipts. + +## Base-selection disposition + +**Canonical-repository exception:** this release is a focused improvement inside the existing Brief2Ship repository. No alternative implementation base or new runtime dependency was required. + +**Disposition:** `selective-reuse` of the canonical repository, existing package/release machinery, open Agent Skills layout, GitHub Actions, and existing public proof receipts. + +## Baseline audit + +Authenticated pre-change GitHub evidence: + +- 3 stars, including the owner; 2 external stars; +- 27 unique visitors and 42 views in the available 14-day traffic window; +- 17 unique cloners and 35 clones; +- Reddit was the only material external referrer; +- exact-name web search found the repository; +- six generic GitHub repository queries did not return Brief2Ship in their first 100 results; +- no custom social preview, homepage URL, profile pins, Discussions, issue templates, pull-request template, or Code of Conduct; +- GitHub community profile health: 71%; +- PyPI project JSON endpoint: HTTP 404. + +This is a funnel baseline, not a causal attribution model. + +## Discoverability changes + +- sharpened the top-level category around repo-first discovery for AI coding agents; +- moved the runnable quickstart, real dogfood result, comparison, and proof above detailed workflow internals; +- added a deterministic terminal GIF sourced from the published v0.6.0 dogfood receipt; +- added a 1280×640 custom social-preview PNG plus editable SVG source; +- added three evidence-bounded decision cases, including `selective-reuse` and justified `build-clean` outcomes; +- expanded Python package keywords and project URLs; +- added Agent Skills, skills.sh, Hermes, Claude Code plugin, PyPI, and immutable-tag install routes; +- added Claude plugin and self-marketplace manifests; +- added PyPI Trusted Publishing workflow with environment-scoped OIDC and release-tag/version validation; +- added issue forms, pull-request template, Code of Conduct, roadmap, and Discussions routes. + +## Safety and scope + +- no core runtime dependency added; +- no candidate repository code executed; +- no network-safety boundary weakened; +- no credentials, private repository names, private URLs, or personal receipt data added; +- launch copy makes no fabricated time-saved, download, adoption, or quality claim; +- demo output is explicitly tied to an existing public dogfood receipt; +- build and source-distribution validation remains mandatory before publication. + +## Local verification + +```text +Documentation contract: passed +Python 3.11: 145 tests passed in 16.626s +Python 3.12: 145 tests passed in 17.318s +Python 3.13: 145 tests passed in 17.179s +Ruff 0.16.5 critical selectors E9,F63,F7,F82: passed +Pyright: 0 errors, 0 warnings, 0 informations +Actionlint 1.7.12: CI and PyPI workflows passed +GitHub CLI 2.100.0 Agent Skills dry-run: passed +Claude Code 2.1.201 plugin/marketplace validation: passed +skills.sh CLI local repository discovery: found exactly brief2ship +git diff --check: passed +Twine distribution metadata check: wheel and sdist passed +Extracted sdist on Python 3.13: 145 tests passed in 17.588s +Clean wheel install: brief2ship 0.6.2 +Installed local discovery: local/brief2ship, 73.50/100, inspected, selective-reuse +Live HTTPS positive control: https://example.com/ succeeded with robots receipt +TLS negative control: wrong.host.badssl.com rejected for hostname mismatch, exit 3 +Social preview visual audit: PASS at 1280×640 and 640×320 +README GIF first/final frame visual audit: PASS at 640×500 and phone scale +``` + +Exact release-candidate artifacts: + +```text +brief2ship-0.6.2-py3-none-any.whl +bytes: 59357 +SHA-256: 34a1e6ad199a94d440364a979d49c8cda0f44fe6eeb81d4d110d4bc845c72e5d + +brief2ship-0.6.2.tar.gz +bytes: 399545 +SHA-256: 70531e30c77fca532c4ab4d999b7ec19286357fe7112f45ca76036acaa964a55 +``` + +Marketing artifacts: + +```text +social-preview.png: 1280×640, 164722 bytes +SHA-256: 9886ef38ca96285d88bf4f4500000cd272c8884a36b92fa5a27e8509543d7591 + +brief2ship-demo.gif: 640×500, 100279 bytes +SHA-256: 4044ce284a0c86c9c9601a5835e0f0ddad416684ba7be650fc1bead21e688b8b +``` + +An initial extracted-sdist run exposed two packaging defects: the pull-request template was omitted from `MANIFEST.in`, and a case-study link targeted a release receipt intentionally excluded from packages. Both were corrected. A later independent blocker review found that wildcard release-asset patterns could admit extra distributions not covered by `SHA256SUMS`. The workflow now derives two exact filenames from `VERSION`, requires the release directory and checksum file to contain exactly those two distributions, runs Twine before the final integrity verifier, and uploads only those exact paths. The rebuilt extracted sdist passed all 145 tests. + +## PyPI + +Trusted Publishing workflow source is included. It is deliberately manual-only and refuses non-tag refs, preventing an unconfigured pending publisher from turning the GitHub release into a false failed-publish signal. Source validation and exact GitHub-release asset checksum verification occur in a separate read-only job; only the two-step artifact-download/publish job receives `id-token: write`. The workflow publishes the same tested wheel and sdist attached to the GitHub release rather than rebuilding timestamp-varying archives. Publication requires the PyPI project or pending publisher to trust: + +```text +owner: five0nit +repository: brief2ship +workflow: publish-pypi.yml +environment: pypi +``` + +Publication status: pending authentication/configuration and exact-tag release. + +## Agent Skills + +The exact v0.6.2 `skills/brief2ship/SKILL.md` passed `gh skill publish --dry-run` under GitHub CLI 2.100.0. The command warned only that no active tag-protection ruleset exists. Local skills.sh discovery found exactly one installable skill named `brief2ship`. + +## Remote gates + +1. Commit the exact candidate on a dedicated branch. +2. Require the pull-request GitHub Actions matrix to pass. +3. Merge and require the exact `main` SHA matrix to pass. +4. Tag that exact SHA as `v0.6.2`. +5. Publish the GitHub release and exact locally tested artifacts. +6. Download release assets and compare SHA-256 values. +7. Verify raw tagged README, skill, manifests, community files, and social assets. +8. Publish to PyPI only through the configured trusted workflow and verify the project/version/install readback. +9. Verify GitHub Agent Skills and skills.sh discovery from the immutable tag. + +## External effects + +At candidate creation time: no GitHub repository settings, profile settings, issue, Discussion, tag, release, package registry, service, gateway, or credential setting had changed. diff --git a/pyproject.toml b/pyproject.toml index 25d8d02..1ad61ba 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,14 +4,25 @@ build-backend = "setuptools.build_meta" [project] name = "brief2ship" -version = "0.6.1" -description = "Repo-first code discovery, safe public research, and verified delivery from one brief." +version = "0.6.2" +description = "Repo-first discovery for AI coding agents: search and score existing code before building, then ship with proof." readme = "README.md" requires-python = ">=3.11" license = "MIT" license-files = ["LICENSE"] authors = [{ name = "Michael Costea" }] -keywords = ["ai-agents", "code-search", "package-search", "web-scraping", "research", "workflow", "receipts"] +keywords = [ + "agent-skills", + "ai-agents", + "ai-coding", + "code-search", + "coding-agents", + "package-search", + "repo-first", + "repository-discovery", + "verified-delivery", + "web-scraping", +] classifiers = [ "Development Status :: 4 - Beta", "Environment :: Console", @@ -35,6 +46,9 @@ brief2ship = "brief2ship.cli:main" Homepage = "https://github.com/five0nit/brief2ship" Repository = "https://github.com/five0nit/brief2ship" Issues = "https://github.com/five0nit/brief2ship/issues" +Documentation = "https://github.com/five0nit/brief2ship#readme" +Changelog = "https://github.com/five0nit/brief2ship/blob/main/CHANGELOG.md" +"Agent Skill" = "https://github.com/five0nit/brief2ship/tree/main/skills/brief2ship" [tool.setuptools.packages.find] where = ["src"] diff --git a/scripts/validate-docs.py b/scripts/validate-docs.py index 9ac5e7d..aac89af 100755 --- a/scripts/validate-docs.py +++ b/scripts/validate-docs.py @@ -20,8 +20,14 @@ "robots.txt required", "zero-paid-API", "heygen-com/hyperframes", + "Stop AI coding agents from rebuilding what already exists", + "gh skill install five0nit/brief2ship", + "npx skills add five0nit/brief2ship", + "claude plugin marketplace add five0nit/brief2ship", + "docs/case-studies.md", ], "CHANGELOG.md": [ + "0.6.2", "0.6.1", "0.6.0", "0.5.1", @@ -32,6 +38,21 @@ "0.3.0", "Report / Document as a fourth default lane", ], + "ROADMAP.md": [ + "v0.6.x distribution and adoption", + "v0.7 evidence quality", + "Non-goals", + ], + "CODE_OF_CONDUCT.md": [ + "Contributor Covenant Code of Conduct", + "Enforcement Guidelines", + ], + "docs/case-studies.md": [ + "Dogfooding found the canonical local project", + "specialist avatar base", + "build-clean", + "70.50/100", + ], "docs/lanes.md": [ "## 4. Report / Document", "executive summaries", @@ -96,6 +117,13 @@ "Hyperframes", "141 tests passed", ], + "docs/releases/v0.6.2-discoverability-receipt.md": [ + "Brief2Ship v0.6.2", + "Canonical-repository exception", + "Agent Skills", + "PyPI", + "Release candidate", + ], "docs/releases/v0.6.0-single-search-skill-receipt.md": [ "PUBLIC RELEASE — VERIFIED", "sole repository/package/local-workspace search and base-selection skill", diff --git a/scripts/verify-release-assets.py b/scripts/verify-release-assets.py new file mode 100644 index 0000000..4ce945c --- /dev/null +++ b/scripts/verify-release-assets.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +"""Verify the exact Brief2Ship release assets and SHA256SUMS contract.""" + +from __future__ import annotations + +import argparse +import hashlib +import hmac +import re +import sys +from pathlib import Path + +_HASH_LINE = re.compile(r"(?P[0-9a-f]{64}) (?P[A-Za-z0-9][A-Za-z0-9._-]*)") + + +def _sha256(path: Path) -> str: + digest = hashlib.sha256() + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(1024 * 1024), b""): + digest.update(chunk) + return digest.hexdigest() + + +def verify(directory: Path, version: str) -> tuple[str, str]: + if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", version): + raise ValueError(f"invalid release version: {version!r}") + if not directory.is_dir(): + raise ValueError(f"release directory does not exist: {directory}") + + wheel = f"brief2ship-{version}-py3-none-any.whl" + sdist = f"brief2ship-{version}.tar.gz" + expected = {wheel, sdist, "SHA256SUMS"} + actual = {path.name for path in directory.iterdir()} + if actual != expected: + raise ValueError( + f"release directory must contain exactly {sorted(expected)!r}; observed {sorted(actual)!r}" + ) + + for name in expected: + path = directory / name + if path.is_symlink() or not path.is_file(): + raise ValueError(f"release asset must be a regular non-symlink file: {name}") + + lines = (directory / "SHA256SUMS").read_text(encoding="ascii").splitlines() + if len(lines) != 2: + raise ValueError(f"SHA256SUMS must contain exactly two lines; observed {len(lines)}") + + declared: dict[str, str] = {} + for line in lines: + match = _HASH_LINE.fullmatch(line) + if match is None: + raise ValueError(f"invalid SHA256SUMS line: {line!r}") + name = match.group("name") + if name in declared: + raise ValueError(f"duplicate SHA256SUMS entry: {name}") + declared[name] = match.group("digest") + + if set(declared) != {wheel, sdist}: + raise ValueError( + f"SHA256SUMS must name exactly {[wheel, sdist]!r}; observed {sorted(declared)!r}" + ) + + for name, expected_digest in declared.items(): + observed = _sha256(directory / name) + if not hmac.compare_digest(observed, expected_digest): + raise ValueError( + f"SHA-256 mismatch for {name}: expected {expected_digest}, observed {observed}" + ) + + return wheel, sdist + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--directory", type=Path, required=True) + parser.add_argument("--version", required=True) + args = parser.parse_args() + try: + wheel, sdist = verify(args.directory, args.version) + except ValueError as exc: + print(f"release asset verification failed: {exc}", file=sys.stderr) + return 1 + print(f"Release assets verified: {wheel}, {sdist}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/skills/brief2ship/SKILL.md b/skills/brief2ship/SKILL.md index fde310d..f20c01d 100644 --- a/skills/brief2ship/SKILL.md +++ b/skills/brief2ship/SKILL.md @@ -1,7 +1,7 @@ --- name: brief2ship 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.6.1 +version: 0.6.2 author: Hermes Agent license: MIT platforms: [linux, macos, windows] diff --git a/src/brief2ship/__init__.py b/src/brief2ship/__init__.py index 9b01355..9d68dc1 100644 --- a/src/brief2ship/__init__.py +++ b/src/brief2ship/__init__.py @@ -1,6 +1,6 @@ """Brief2Ship public package.""" -__version__ = "0.6.1" +__version__ = "0.6.2" from .discovery import discover from .discovery_models import Candidate, DiscoveryConfig, DiscoveryResult diff --git a/src/brief2ship/discovery_http.py b/src/brief2ship/discovery_http.py index 1bc97e0..2178e99 100644 --- a/src/brief2ship/discovery_http.py +++ b/src/brief2ship/discovery_http.py @@ -44,7 +44,7 @@ def __init__( timeout: float = 20.0, total_timeout: float | None = None, github_token: str | None = None, - user_agent: str = "Brief2ShipBot/0.6.1 (+https://github.com/five0nit/brief2ship)", + user_agent: str = "Brief2ShipBot/0.6.2 (+https://github.com/five0nit/brief2ship)", ) -> None: self.timeout = timeout self._expires_at = time.monotonic() + total_timeout if total_timeout is not None else None diff --git a/src/brief2ship/models.py b/src/brief2ship/models.py index e19ca8c..52bc24a 100644 --- a/src/brief2ship/models.py +++ b/src/brief2ship/models.py @@ -6,7 +6,7 @@ from typing import Any -DEFAULT_USER_AGENT = "Brief2ShipBot/0.6.1 (+https://github.com/five0nit/brief2ship)" +DEFAULT_USER_AGENT = "Brief2ShipBot/0.6.2 (+https://github.com/five0nit/brief2ship)" @dataclass(frozen=True) diff --git a/tests/test_release_contract.py b/tests/test_release_contract.py index 47b77dd..dd21303 100644 --- a/tests/test_release_contract.py +++ b/tests/test_release_contract.py @@ -1,4 +1,10 @@ +import hashlib +import json import re +import struct +import subprocess +import sys +import tempfile import tomllib import unittest from pathlib import Path @@ -13,7 +19,7 @@ def test_version_is_consistent(self): init = (ROOT / "src/brief2ship/__init__.py").read_text(encoding="utf-8") skill = (ROOT / "skills/brief2ship/SKILL.md").read_text(encoding="utf-8") changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8") - self.assertEqual("0.6.1", version) + self.assertEqual("0.6.2", version) self.assertEqual(version, pyproject["project"]["version"]) self.assertIn(f'__version__ = "{version}"', init) self.assertIn(f"version: {version}", skill) @@ -195,9 +201,103 @@ def test_relative_markdown_links_exist(self): def test_readme_does_not_link_to_receipts_excluded_from_packages(self): readme = (ROOT / "README.md").read_text(encoding="utf-8") self.assertNotRegex(readme, r"\]\(docs/releases/") - self.assertIn("`docs/releases/v0.6.1-single-search-skill-receipt.md`", readme) + self.assertIn("`docs/releases/v0.6.2-discoverability-receipt.md`", readme) self.assertIn("outside built packages", readme) + def test_discovery_marketing_and_community_surfaces(self): + readme = (ROOT / "README.md").read_text(encoding="utf-8") + self.assertLess( + readme.index("Stop AI coding agents from rebuilding what already exists"), + readme.index("## 30-second quickstart"), + ) + self.assertLess(readme.index("## 30-second quickstart"), readme.index("## Why Brief2Ship?")) + for rel in [ + "CODE_OF_CONDUCT.md", + "ROADMAP.md", + "docs/case-studies.md", + ".github/ISSUE_TEMPLATE/bug.yml", + ".github/ISSUE_TEMPLATE/feature.yml", + ".github/PULL_REQUEST_TEMPLATE.md", + ]: + self.assertTrue((ROOT / rel).is_file(), rel) + + png = (ROOT / "docs/assets/social-preview.png").read_bytes() + self.assertEqual(b"\x89PNG\r\n\x1a\n", png[:8]) + self.assertEqual((1280, 640), struct.unpack(">II", png[16:24])) + self.assertLess(len(png), 1_000_000) + + gif = (ROOT / "docs/assets/brief2ship-demo.gif").read_bytes() + self.assertIn(gif[:6], (b"GIF87a", b"GIF89a")) + self.assertEqual((640, 500), struct.unpack("