diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..1adcaa9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,29 @@ +--- +name: Bug report +about: Something in the CLI / ingest / compile pipeline isn't working +title: "bug: " +labels: bug +--- + +## What happened + + +## Steps to reproduce +1. +2. +3. + +## Expected vs actual +- Expected: +- Actual: + +## Context +- Source kind (if relevant): blog / YouTube / repo / PDF +- Source URL or minimal repro (if relevant): +- Command run (e.g. `mask ingest …`, or `bun run dev …`): +- Adapter: claude-code / agents-md +- OS + Bun version (`bun --version`): +- yt-dlp / git / pdftotext version (if the bug is source-specific): + +## Logs / output + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..9cd35e6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: Developer guide (AGENTS.md) + url: https://github.com/TTigger/mask/blob/main/AGENTS.md + about: How the codebase is structured and the house rules — read before contributing. + - name: Docs (PRD / SPEC / PHASES) + url: https://github.com/TTigger/mask/tree/main/docs + about: Design background for the framework. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..13c6ea0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,18 @@ +--- +name: Feature request +about: Suggest a new source, adapter, or capability +title: "feat: " +labels: enhancement +--- + +## Problem / motivation + + +## Proposed solution + + +## Alternatives considered + + +## Notes + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..c2127ac --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,15 @@ + + +## What & why + + +## How + + +## Checklist +- [ ] `bun run typecheck` passes +- [ ] `bun test` passes +- [ ] `bun run build` passes (if touching the binary / embedded assets) +- [ ] External tools stay injectable; new logic is unit-tested offline (no network in tests) +- [ ] The CLI still calls no LLM; no API keys added +- [ ] Conventional-commit title (e.g. `fix(youtube): …`) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1fdc7c1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +# Contributing to mask + +Thanks for helping out! mask is small, deterministic, and agent-native — contributions that keep it that way are easy to land. + +> The full developer guide lives in **[AGENTS.md](AGENTS.md)** (read by Claude Code, Codex, Cursor, Gemini, …). This page is the short version; AGENTS.md is the source of truth. + +## Dev setup + +Requires [Bun](https://bun.sh). + +```sh +git clone https://github.com/TTigger/mask && cd mask +bun install +bun run dev # run the CLI straight from the clone, e.g. `bun run dev list` +``` + +## Before you open a PR + +Run the same three checks CI runs (see `.github/workflows/ci.yml`): + +```sh +bun run typecheck # tsc --noEmit +bun test # the deterministic-core suite +bun run build # single executable — needed for anything touching the binary / embedded assets +``` + +Keep the tree green between commits. + +## House rules (the short list) + +- **The CLI calls no LLM.** Everything under `src/` is deterministic; the "intelligence" is borrowed from the user's agent following a recipe. The only sanctioned exception is `mask scale` (shells out to the user's *own* headless agent CLI). Never add a model API or key. +- **Framework ≠ library.** This repo is the tool; a user's masks live in `~/.mask/`. Don't store masks here. +- **External tools are injectable.** New ingest modules take a fetcher/provider/extractor that defaults to the real tool (git / yt-dlp / pdftotext) with a fake in tests — the suite must run offline. Prefer extracting pure helpers and unit-testing those (see `parseVtt`, `pickSubtitleLang`). +- **Evidence-bound output.** Distilled claims trace to a source sample `[src:id]`; thin coverage is declared, not hidden. +- **Add an agent** via an adapter, **add a source** via an ingest module — the recipe stays put. The three layers are independent. + +## Commits & PRs + +- One minimal, verifiable change per commit. +- Conventional-commit messages, e.g. `fix(youtube): …`, `feat(ingest): …`, `docs: …`. +- Keep the PR focused; fill in the PR template checklist. + +## Reporting bugs / proposing features + +Open an issue using the templates. For ingest bugs, include the source kind (blog / YouTube / repo / PDF) and, if relevant, the URL or a minimal repro. diff --git a/README.md b/README.md index 9f96edd..40945f9 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,10 @@ The CLI is deterministic and calls **no LLM** — your agent does the intelligen - `MASK_AGENTS_MD` — the AGENTS.md install target (default `./AGENTS.md`; `init --out ` sets this). - `MASK_FRAMEWORK` — set this when running the **standalone compiled binary** so the agent can still find the on-disk recipe/templates; point it at the cloned repo. (Unnecessary with `bun run`/`bunx`, which resolve them automatically.) +## Contributing + +Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) (and [AGENTS.md](AGENTS.md) for the full developer guide). + ## License MIT diff --git a/README.zh-TW.md b/README.zh-TW.md index a368dec..8690115 100644 --- a/README.zh-TW.md +++ b/README.zh-TW.md @@ -108,6 +108,10 @@ CLI 是決定性的、**不呼叫任何 LLM** —— 智慧工作由你的 agent - `MASK_AGENTS_MD` —— AGENTS.md 安裝目標（預設 `./AGENTS.md`；`init --out ` 會設定它）。 - `MASK_FRAMEWORK` —— 跑**獨立編譯二進位**時設定，讓 agent 仍找得到磁碟上的 recipe/templates；指向 clone 的 repo。（用 `bun run`/launcher 時不需要，會自動解析。） +## 參與貢獻 + +歡迎開 issue 與 PR —— 請看 [CONTRIBUTING.md](CONTRIBUTING.md)（完整開發指南在 [AGENTS.md](AGENTS.md)）。 + ## License MIT