mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-03-20 12:11:28 -07:00
96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
# AGENTS.MD
|
||
|
||
## 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.
|
||
- When merging a PR: thank the contributor in `CHANGELOG.md`.
|
||
|
||
## 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.
|
||
|
||
## Docs
|
||
|
||
- The documentation for this project lives in a separate sister directory: [`../subminer-docs/`](https://github.com/ksyasuda/subminer-docs)
|
||
- Read the [`../subminer-docs/development.md`](https://github.com/ksyasuda/subminer-docs/blob/main/development.md) and [`../subminer-docs/architecture.md`](https://github.com/ksyasuda/subminer-docs/blob/main/architecture.md) before making changes and follow the guidelines unless there is a specific reason to deviate
|
||
- Make sure the changelog [`../subminer-docs/changelog.md`](https://github.com/ksyasuda/subminer-docs/blob/main/changelog.md) is updated on each release
|
||
- Ensure the docs are kept up to date if any new or breaking changes are introduced
|
||
- If the sister repo does not exist at `../subminer-docs`, then do not attempt
|
||
to update the docs and reference the files from GitHub if needed
|
||
|
||
## Flow & Runtime
|
||
|
||
- Use repo’s package manager/runtime; no swaps w/o approval.
|
||
- Use Codex background for long jobs; tmux only for interactive/persistent (debugger/server).
|
||
|
||
## Build / Test
|
||
|
||
- Before handoff: run full gate (lint/typecheck/tests/docs).
|
||
- CI red: `gh run list/view`, rerun, fix, push, repeat til green.
|
||
- Keep it observable (logs, panes, tails, MCP/browser tools).
|
||
|
||
## Git
|
||
|
||
- Safe by default: `git status/diff/log`. Push only when user asks.
|
||
- `git checkout` ok for PR review / explicit request.
|
||
- Branch changes require user consent.
|
||
- Destructive ops forbidden unless explicit (`reset --hard`, `clean`, `restore`, `rm`, …).
|
||
- Don’t delete/rename unexpected stuff; stop + ask.
|
||
- No repo-wide S/R scripts; keep edits small/reviewable.
|
||
- Avoid manual `git stash`; if Git auto-stashes during pull/rebase, that’s fine (hint, not hard guardrail).
|
||
- If user types a command (“pull and push”), that’s consent for that command.
|
||
- No amend unless asked.
|
||
- Big review: `git --no-pager diff --color=never`.
|
||
- Multi-agent: check `git status/diff` before edits; ship small commits.
|
||
|
||
## 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.
|
||
|
||
## macOS Permissions / Signing (TCC)
|
||
|
||
- Never re-sign / ad-hoc sign / change bundle ID as “debug” without explicit ok (can mess TCC).
|
||
|
||
<!-- 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 -->
|