mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-03-20 03:16:46 -07:00
107 lines
4.6 KiB
Markdown
107 lines
4.6 KiB
Markdown
# AGENTS.MD
|
|
|
|
## Quick Start
|
|
|
|
- Read [`docs-site/development.md`](./docs-site/development.md) and [`docs-site/architecture.md`](./docs-site/architecture.md) before substantial changes; follow them unless task requires deviation.
|
|
- Init workspace: `git submodule update --init --recursive`.
|
|
- Install deps: `make deps` or `bun install` plus `(cd vendor/texthooker-ui && bun install --frozen-lockfile)`.
|
|
- Fast dev loop: `make dev-watch`.
|
|
- Full local run: `bun run dev`.
|
|
- Verbose Electron debug: `electron . --start --dev --log-level debug`.
|
|
|
|
## Build / Test
|
|
|
|
- Use repo package manager/runtime only: Bun (`packageManager: bun@1.3.5`).
|
|
- Default handoff gate:
|
|
`bun run typecheck`
|
|
`bun run test:fast`
|
|
`bun run test:env`
|
|
`bun run build`
|
|
`bun run test:smoke:dist`
|
|
- If `docs-site/` changed, also run:
|
|
`bun run docs:test`
|
|
`bun run docs:build`
|
|
- Formatting: prefer `make pretty` and `bun run format:check:src`; use `bun run format` only intentionally.
|
|
- Keep verification observable; capture failing command + exact error in notes/handoff.
|
|
|
|
## Change-Specific Checks
|
|
|
|
- Config/schema/defaults changes: run `bun run test:config`; if config template/defaults changed, run `bun run generate:config-example`.
|
|
- Launcher/plugin changes: run `bun run test:launcher` or `bun run test:env`; use `bun run test:launcher:smoke:src` for focused launcher e2e checks.
|
|
- Runtime-compat or compiled/dist-sensitive changes: run `bun run test:runtime:compat`.
|
|
- Docs-only changes: at least `bun run docs:test` if docs behavior/assertions changed; `bun run docs:build` before handoff.
|
|
|
|
## Generated / Sensitive Files
|
|
|
|
- Launcher source of truth: `launcher/*.ts`.
|
|
- Generated launcher artifact: `dist/launcher/subminer`; never hand-edit it.
|
|
- Repo-root `./subminer` is stale artifact path; do not revive/use it.
|
|
- `bun run build` rebuilds bundled Yomitan from `vendor/subminer-yomitan`; check submodules before debugging build failures.
|
|
- Avoid changing packaging/signing identifiers (`build.appId`, mac entitlements, signing-related settings) unless task explicitly requires it.
|
|
|
|
## Docs
|
|
|
|
- Docs site lives in-repo under [`docs-site/`](./docs-site/).
|
|
- Update docs for new/breaking behavior; no ship with stale docs.
|
|
- Make sure [`docs-site/changelog.md`](./docs-site/changelog.md) is updated on each release.
|
|
|
|
## PR Feedback
|
|
|
|
- Active PR: `gh pr view --json number,title,url --jq '"PR #\\(.number): \\(.title)\\n\\(.url)"'`.
|
|
- PR comments: `gh pr view …` + `gh api …/comments --paginate`.
|
|
- Replies: cite fix + file/line; resolve threads only after fix lands.
|
|
|
|
## Changelog
|
|
|
|
- User-visible PRs: add one fragment in `changes/*.md`.
|
|
- Fragment format:
|
|
`type: added|changed|fixed|docs|internal`
|
|
`area: <short-area>`
|
|
blank line
|
|
`- bullet`
|
|
- `changes/README.md`: instructions only; generator ignores it.
|
|
- No release-note entry wanted: use PR label `skip-changelog`.
|
|
- CI runs `bun run changelog:lint` + `bun run changelog:pr-check` on PRs.
|
|
- Release prep: `bun run changelog:build`, review `CHANGELOG.md` + `release/release-notes.md`, commit generated changelog + fragment deletions, then tag.
|
|
- Release CI expects committed changelog entry already present; do not rely on tag job to invent notes.
|
|
|
|
## Flow & Runtime
|
|
|
|
- Use Codex background for long jobs; tmux only for interactive/persistent (debugger/server).
|
|
- CI red: `gh run list/view`, rerun, fix, push, repeat til green.
|
|
|
|
## Language/Stack Notes
|
|
|
|
- Swift: use workspace helper/daemon; validate `swift build` + tests; keep concurrency attrs right.
|
|
- TypeScript: use repo PM; keep files small; follow existing patterns.
|
|
|
|
<!-- BACKLOG.MD MCP GUIDELINES START -->
|
|
|
|
<CRITICAL_INSTRUCTION>
|
|
|
|
## BACKLOG WORKFLOW INSTRUCTIONS
|
|
|
|
This project uses Backlog.md MCP for all task and project management activities.
|
|
|
|
**CRITICAL GUIDANCE**
|
|
|
|
- If your client supports MCP resources, read `backlog://workflow/overview` to understand when and how to use Backlog for this project.
|
|
- If your client only supports tools or the above request fails, call `backlog.get_workflow_overview()` tool to load the tool-oriented overview (it lists the matching guide tools).
|
|
|
|
- **First time working here?** Read the overview resource IMMEDIATELY to learn the workflow
|
|
- **Already familiar?** You should have the overview cached ("## Backlog.md Overview (MCP)")
|
|
- **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work
|
|
|
|
These guides cover:
|
|
|
|
- Decision framework for when to create tasks
|
|
- Search-first workflow to avoid duplicates
|
|
- Links to detailed guides for task creation, execution, and finalization
|
|
- MCP tools reference
|
|
|
|
You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here.
|
|
|
|
</CRITICAL_INSTRUCTION>
|
|
|
|
<!-- BACKLOG.MD MCP GUIDELINES END -->
|