From 2f2cb163f73a395dc9e6a4830c3b0f3ad6ee2ed7 Mon Sep 17 00:00:00 2001 From: is0692vs Date: Tue, 14 Apr 2026 09:58:51 +0900 Subject: [PATCH 1/4] docs(agent-tooling): add shared agent workflow docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/pr-consolidation-playbook.md | 2 + .github/agents/pr-review-closure-loop.md | 2 + .github/copilot-instructions.md | 116 +++----------------- AGENTS.md | 13 +++ README.md | 8 ++ docs/agent-tooling.md | 52 +++++++++ instruction.md | 27 ++--- 7 files changed, 102 insertions(+), 118 deletions(-) create mode 100644 AGENTS.md create mode 100644 docs/agent-tooling.md diff --git a/.github/agents/pr-consolidation-playbook.md b/.github/agents/pr-consolidation-playbook.md index e1128ee6..6c3cd77e 100644 --- a/.github/agents/pr-consolidation-playbook.md +++ b/.github/agents/pr-consolidation-playbook.md @@ -17,6 +17,8 @@ user-invocable: true This document defines a repeatable workflow for consolidating many similar open PRs into a smaller set of target PRs. +Shared tooling reference: `../../AGENTS.md` and `../../docs/agent-tooling.md`. + ## Objective - Group similar PRs by scope (e.g., same file, same feature area, same intent). diff --git a/.github/agents/pr-review-closure-loop.md b/.github/agents/pr-review-closure-loop.md index 00a8ff0c..6da72a4e 100644 --- a/.github/agents/pr-review-closure-loop.md +++ b/.github/agents/pr-review-closure-loop.md @@ -20,6 +20,8 @@ user-invocable: true You are a specialist for closing PR review feedback loops with traceable decisions. Your job is to eliminate unattended review comments while keeping CI green. +Shared tooling reference: `../../AGENTS.md` and `../../docs/agent-tooling.md`. + ## Mission - For each unresolved review conversation in an open PR, classify the comment as: diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 201671ef..8de940d6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,6 +7,16 @@ applyTo: "**" **OpenShelf** is a research artifact hosting and sharing platform where users authenticate with GitHub OAuth to upload and share research outputs (papers, slides, datasets). The stack is a TypeScript monorepo deployed on Cloudflare's edge platform. +## Agent entry points + +If you only need one starting point, open `AGENTS.md`. + +- `AGENTS.md` — universal index for every agent +- `docs/agent-tooling.md` — shared Dosu / Notion / ntn workflow and knowledge capture rules +- `.github/agents/pr-review-closure-loop.md` — PR review conversation closure loop +- `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow +- `instruction.md` — legacy guide kept for compatibility + ## Quick Reference | Component | Tech | Location | @@ -255,96 +265,11 @@ Run `npm run typecheck` before committing to catch TS errors. --- -### Responding to PR Reviews - -**Overview:** For each PR review comment, you must reply via GitHub's conversation API, resolve the thread, and verify all conversations are addressed before merging. - -**Detailed Workflow:** - -1. **Fetch and review all conversations** - - ```bash - gh pr view --json reviews - ``` - -2. **For each conversation thread**, choose one of two paths: - - **Path A: Accepting the suggestion** - - Apply the change to your branch and commit: - ```bash - # Make edits, then: - git add . - git commit -m "Address review: " - git push - ``` - - Reply to the conversation explaining the fix: - ```bash - gh pr comment --body "✅ Applied in commit $(git rev-parse --short HEAD). Changes: " - ``` - - Mark as resolved on GitHub (via web UI or after approval) - - **Path B: Declining or deferring** - - Reply with justification: - ```bash - gh pr comment --body "⚠️ Deferred for future work because: . Tracked in #XYZ" - ``` - - Resolve the conversation (indicate it won't be addressed in this PR) - -3. **Verify all conversations are resolved** - - ```bash - # Check for unresolved review threads - gh pr view --json reviews | grep -i "pending\|unresolved" - ``` - - Status should be empty (no pending reviews). - -4. **Check CI status** - - ```bash - gh pr checks - ``` - - - **All passing?** → Proceed to merge - - **Any failing?** → Investigate and fix: - ```bash - gh pr checks --watch # Real-time logs - ``` - -5. **Final approval and merge** - - ```bash - # Wait for any last-minute feedback - sleep 300 && gh pr checks - - # If all checks pass and reviews approved: - gh pr merge --squash --delete-branch - ``` +### PR Review Playbooks -**Conversation Checklist:** - -- ☐ All comments have a reply (accept or defer) -- ☐ All accepted changes are committed and pushed -- ☐ All deferred changes reference a tracking issue -- ☐ All threads marked as resolved on GitHub -- ☐ CI checks are passing -- ☐ Code review approval(s) received - -**Example Command Sequence:** - -```bash -# Check PR status -gh pr view 42 - -# Wait and re-check CI after making changes -sleep 300 && gh pr checks 42 - -# Watch CI in real-time -gh pr checks 42 --watch - -# Once ready, merge -gh pr merge 42 --squash -``` +- Detailed review-thread closure: `.github/agents/pr-review-closure-loop.md` +- Detailed PR consolidation: `.github/agents/pr-consolidation-playbook.md` +- Use those playbooks as the source of truth for reply/resolve loops and absorbed-PR handling. --- @@ -424,7 +349,7 @@ See `apps/web/README.md` and `apps/api/wrangler.toml` for environment variable r ## Notes for Agents -- Always check `.github/copilot-instructions.md` **first** for project-specific conventions. +- Always check `AGENTS.md` **first** for shared agent workflow, then this file for project-specific conventions. - Use `npm run typecheck` and `npm run test` to validate changes before pushing. - E2E tests require both `apps/api` and `apps/web` running; Playwright auto-starts them. - For database changes, test locally with `db:migrate:local` before planning remote migrations. @@ -437,11 +362,6 @@ See `apps/web/README.md` and `apps/api/wrangler.toml` for environment variable r ### PR Workflow Reminders -- **New features:** Always create a feature branch and open a PR; never commit directly to `main`. -- **Staging-first deployment:** Treat `staging` as the first merge target for feature work. Verify there, then open a `staging` → `main` PR for production. -- **PR retargeting:** If a PR to `main` is opened from a non-`staging` source branch, the workflow will retarget it to `staging`. -- **main sync:** After pushes to `main`, rely on the automation that opens or reuses a `main` → `staging` sync PR. -- **PR reviews:** Reply to _each_ conversation thread on GitHub; unresolved threads block merging. -- **CI failures:** Investigate immediately via `gh pr checks --watch` and fix before re-requesting review. -- **Merge readiness checklist:** All conversations resolved + all CI passing + approval received = safe to merge. -- **Use `sleep` + recheck pattern:** `sleep 300 && gh pr checks ` to let CI run before final checks. +- Use `.github/agents/pr-review-closure-loop.md` for the full review / CI loop. +- Use `.github/agents/pr-consolidation-playbook.md` for PR consolidation. +- Keep `staging` as the first merge target for feature work. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..dfc4f811 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,13 @@ +# AGENTS.md + +This is the universal entry point for agents working in OpenShelf. + +Start here: + +- `docs/agent-tooling.md` — shared Dosu / Notion / ntn workflow and knowledge-capture rules +- `.github/copilot-instructions.md` — OpenShelf repository conventions and coding workflow +- `.github/agents/pr-review-closure-loop.md` — PR review conversation closure loop +- `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow +- `instruction.md` — legacy guide kept for compatibility + +Keep shared guidance in one place and link to it instead of copying it into multiple files. diff --git a/README.md b/README.md index 049f5990..645c2d5c 100644 --- a/README.md +++ b/README.md @@ -224,6 +224,14 @@ cd apps/e2e && npx playwright test --- +## 🤖 エージェント向けドキュメント + +- [`AGENTS.md`](./AGENTS.md) — どのエージェントでも最初に読む共通入口 +- [`docs/agent-tooling.md`](./docs/agent-tooling.md) — Dosu / Notion / ntn の共通ワークフロー +- [`.github/copilot-instructions.md`](./.github/copilot-instructions.md) — OpenShelf 固有の開発ルール + +--- + ## 📄 ライセンス [MIT License](./LICENSE) diff --git a/docs/agent-tooling.md b/docs/agent-tooling.md new file mode 100644 index 00000000..0e7e4605 --- /dev/null +++ b/docs/agent-tooling.md @@ -0,0 +1,52 @@ +# Agent Tooling and Knowledge Workflow + +This is the shared reference for Copilot, Codex, and other agents working in OpenShelf. + +## Entry points + +- `AGENTS.md` — universal index for any agent +- `.github/copilot-instructions.md` — repository conventions and coding workflow +- `.github/agents/pr-review-closure-loop.md` — review-thread closure loop +- `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow +- `instruction.md` — legacy guide kept for compatibility + +## Tool map + +| Need | Use | Notes | +| --- | --- | --- | +| Get repository or domain context | `dosu-init_knowledge` | Start here for unfamiliar or cross-cutting work. | +| Search documentation | `dosu-search_documentation` | Use for broad documentation discovery. | +| Read an authoritative source | `dosu-fetch_source` | Prefer this when exact wording or citations matter. | +| Synthesize an answer with citations | `dosu-ask` | Use after collecting enough context. | +| Capture durable knowledge | `dosu-save_topic` | Save stable, reusable findings only. | +| Find available knowledge sources | `dosu-list_available_data_sources` | Useful before broad searches. | +| Work with Notion | `ntn` | Use for Notion pages, databases, and workers. | +| Set up or authenticate Dosu | `dosu` CLI | Use for login, status, and MCP registration. | + +## Dosu workflow + +1. Start with `dosu-init_knowledge` when the task needs context. +2. Use `dosu-search_documentation` to find likely sources. +3. Use `dosu-fetch_source` for exact source text. +4. Use `dosu-ask` for a cited synthesis once you have enough facts. +5. Use `dosu-save_topic` when the finding is durable, actionable, and likely to help future tasks. + +## Dosu CLI setup + +- `dosu login` to authenticate. +- `dosu status` to confirm account and MCP configuration. +- `dosu mcp add codex -g` to register the MCP target for Codex-compatible tools. + +## Notion CLI workflow + +- Use `ntn` for Notion API tasks, worker operations, page updates, and database queries. +- Start with `ntn --help`, `ntn api --help`, `ntn workers --help`, and `ntn login` when setting up a session. +- If an `ntn api` subcommand cannot load its spec, retry after `ntn login` or confirm the target workspace is reachable. +- Keep Notion work separate from repo code changes unless the task explicitly requires both. + +## Shared rules + +- Prefer links over duplicated guidance. +- Keep task-specific procedures in the specialized playbooks. +- Save knowledge only when it will stay useful across future tasks. +- When a finding is specific to OpenShelf, include the repo name plus the relevant file paths in the saved topic. diff --git a/instruction.md b/instruction.md index 015c8796..9b7c8aaf 100644 --- a/instruction.md +++ b/instruction.md @@ -139,28 +139,15 @@ E2E tests skip real GitHub OAuth by calling `/api/auth/test-token` (only active ## Agent Workflow Guidelines -When you receive instructions, follow these guidelines based on the context: +Use the shared docs instead of restating detailed workflows here: -- **New Feature or Task**: Create a new branch from the default branch and open a Pull Request. -- **Improving an Existing PR/Branch**: Checkout the existing feature branch and push your changes. +- `AGENTS.md` — universal entry point for any agent +- `docs/agent-tooling.md` — Dosu / Notion / ntn workflow +- `.github/agents/pr-review-closure-loop.md` — review-thread closure loop +- `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow -### Agent Playbooks - -- [PR Review Closure Loop](.github/agents/pr-review-closure-loop.md) -- [PR Consolidation Playbook](.github/agents/pr-consolidation-playbook.md) - -### Pull Request Reviews -When responding to PR reviews using the `gh` CLI: -- Always reply to and resolve the GitHub conversation for each comment. -- If accepting a suggestion, apply the change, reply with the commit details explaining how it was addressed, and resolve the conversation. -- If ignoring a suggestion, reply with a clear reason why it is being skipped, and resolve the conversation. -- If a suggestion is implemented with an alternative approach, explain the implementation and the reasoning before resolving the conversation. -- Ensure that the number of unresolved conversations (`isResolved: false`) is strictly 0. - -### CI Status -- If CI is configured, check its status. -- If CI succeeds, proceed. -- If CI fails, check the failure details and address the issues. +- New feature or task: create a branch from the default branch and open a Pull Request. +- Improving an existing PR or branch: check out the existing feature branch and push your changes. ### Language Requirement When interacting on GitHub (e.g., PR descriptions, PR comments, replies), always use Japanese. This applies strictly to GitHub interactions, not to code implementation, variable names, or inline code messages. From 5e3b17154b50477e49e932fde536771adcb66193 Mon Sep 17 00:00:00 2001 From: is0692vs Date: Tue, 14 Apr 2026 10:06:47 +0900 Subject: [PATCH 2/4] docs(agent-tooling): expand Dosu and Notion reference Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- AGENTS.md | 2 +- README.md | 2 +- docs/agent-tooling.md | 168 ++++++++++++++++++++++++++------ instruction.md | 2 +- 5 files changed, 141 insertions(+), 35 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8de940d6..521a8eb0 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -12,7 +12,7 @@ applyTo: "**" If you only need one starting point, open `AGENTS.md`. - `AGENTS.md` — universal index for every agent -- `docs/agent-tooling.md` — shared Dosu / Notion / ntn workflow and knowledge capture rules +- `docs/agent-tooling.md` — shared Dosu / Notion / ntn reference, including CLI, MCP, and knowledge capture rules - `.github/agents/pr-review-closure-loop.md` — PR review conversation closure loop - `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow - `instruction.md` — legacy guide kept for compatibility diff --git a/AGENTS.md b/AGENTS.md index dfc4f811..71b39071 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ This is the universal entry point for agents working in OpenShelf. Start here: -- `docs/agent-tooling.md` — shared Dosu / Notion / ntn workflow and knowledge-capture rules +- `docs/agent-tooling.md` — shared Dosu / Notion / ntn reference, including CLI, MCP, and knowledge-capture rules - `.github/copilot-instructions.md` — OpenShelf repository conventions and coding workflow - `.github/agents/pr-review-closure-loop.md` — PR review conversation closure loop - `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow diff --git a/README.md b/README.md index 645c2d5c..7efa7c72 100644 --- a/README.md +++ b/README.md @@ -227,7 +227,7 @@ cd apps/e2e && npx playwright test ## 🤖 エージェント向けドキュメント - [`AGENTS.md`](./AGENTS.md) — どのエージェントでも最初に読む共通入口 -- [`docs/agent-tooling.md`](./docs/agent-tooling.md) — Dosu / Notion / ntn の共通ワークフロー +- [`docs/agent-tooling.md`](./docs/agent-tooling.md) — Dosu / Notion / ntn の共通参照（CLI / MCP / 知識保存） - [`.github/copilot-instructions.md`](./.github/copilot-instructions.md) — OpenShelf 固有の開発ルール --- diff --git a/docs/agent-tooling.md b/docs/agent-tooling.md index 0e7e4605..622d2319 100644 --- a/docs/agent-tooling.md +++ b/docs/agent-tooling.md @@ -1,52 +1,158 @@ # Agent Tooling and Knowledge Workflow -This is the shared reference for Copilot, Codex, and other agents working in OpenShelf. +This is the canonical reference for Copilot, Codex, and other agents working in OpenShelf. + +Use it when you need to choose between Dosu, Notion CLI (`ntn`), or the Notion/Dosu MCP surfaces. ## Entry points - `AGENTS.md` — universal index for any agent -- `.github/copilot-instructions.md` — repository conventions and coding workflow +- `.github/copilot-instructions.md` — OpenShelf repository conventions and coding workflow - `.github/agents/pr-review-closure-loop.md` — review-thread closure loop - `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow - `instruction.md` — legacy guide kept for compatibility -## Tool map +## What to use when -| Need | Use | Notes | +| Need | Prefer | Why | | --- | --- | --- | -| Get repository or domain context | `dosu-init_knowledge` | Start here for unfamiliar or cross-cutting work. | -| Search documentation | `dosu-search_documentation` | Use for broad documentation discovery. | -| Read an authoritative source | `dosu-fetch_source` | Prefer this when exact wording or citations matter. | -| Synthesize an answer with citations | `dosu-ask` | Use after collecting enough context. | -| Capture durable knowledge | `dosu-save_topic` | Save stable, reusable findings only. | -| Find available knowledge sources | `dosu-list_available_data_sources` | Useful before broad searches. | -| Work with Notion | `ntn` | Use for Notion pages, databases, and workers. | -| Set up or authenticate Dosu | `dosu` CLI | Use for login, status, and MCP registration. | - -## Dosu workflow - -1. Start with `dosu-init_knowledge` when the task needs context. -2. Use `dosu-search_documentation` to find likely sources. +| Find repo or cross-cutting context | `dosu-init_knowledge` | Starts with knowledge discovery instead of guessing. | +| Search docs or runbooks broadly | `dosu-search_documentation` | Good for discovering relevant sources. | +| Read exact source text | `dosu-fetch_source` | Best when wording, lines, or citations matter. | +| Ask for a cited synthesis | `dosu-ask` | Use after you have enough sources. | +| Preserve a stable finding | `dosu-save_topic` | Captures reusable knowledge for later tasks. | +| Work with Notion pages, databases, files, or workers | `ntn` | CLI for workspace operations and worker management. | +| Wire Dosu into an AI tool | `dosu setup` / `dosu mcp add` | Registers Dosu MCP for the current environment. | + +## Dosu CLI + +`dosu --help` shows: + +- `login` +- `logout` +- `status` +- `mcp` +- `setup` +- `logs` + +Use the Dosu CLI when you are configuring access or MCP integration, not when you are searching content. + +Helpful commands: + +```bash +dosu status +dosu login +dosu setup [--deployment ] +dosu mcp add [-g] +dosu mcp list +``` + +Notes: + +- `dosu setup` sets up Dosu MCP for AI tools. +- `dosu mcp add -g` adds the integration globally instead of project-local. +- `dosu status` confirms whether you are logged in and which deployment is active. +- `dosu logs` is the place to look when the integration needs debugging. + +## Dosu knowledge workflow + +1. Start with `dosu-init_knowledge` for unfamiliar or cross-cutting work. +2. Use `dosu-search_documentation` to find candidate sources. 3. Use `dosu-fetch_source` for exact source text. -4. Use `dosu-ask` for a cited synthesis once you have enough facts. -5. Use `dosu-save_topic` when the finding is durable, actionable, and likely to help future tasks. +4. Use `dosu-ask` for a cited answer once you have enough context. +5. Use `dosu-save_topic` when the finding is durable and reusable. + +Other useful Dosu tools: + +- `dosu-list_available_data_sources` +- `dosu-find_public_library` +- `dosu-ask_public_library` + +Use Dosu knowledge tools when the task is about repo understanding, a shared runbook, a cross-file dependency, or a fact that should be reused later. + +## Notion CLI (`ntn`) + +`ntn --help` shows: + +- `api` — public Notion API, beta +- `files` — file uploads, beta +- `pages` +- `login` +- `logout` +- `update` +- `workers` + +Helpful commands: + +```bash +ntn api ls +ntn api --help +ntn api --docs +ntn api --spec +ntn pages create --content '# Title\n\nBody' +ntn files create < file.png +ntn files get +ntn files list +ntn workers list +ntn workers exec --data '{...}' +``` + +Notes: + +- `ntn api ls` reads the live OpenAPI index and does not require authentication. +- `ntn api` is the best way to inspect the public Notion API surface from the CLI. +- `ntn pages` currently focuses on creating pages from Markdown content. +- `ntn files` handles file uploads and retrieval. +- `ntn workers` manages deploy, list, exec, env, oauth, runs, sync, webhooks, and the TUI. + +Common environment variables: + +- `NOTION_API_TOKEN` +- `NOTION_WORKSPACE_ID` +- `NOTION_WORKERS_CONFIG_FILE` +- `NOTION_ENV` +- `NOTION_HOME` + +Use `ntn` when you need to operate on Notion content directly or when you need worker lifecycle commands. + +## Notion MCP / API + +Notion docs describe Notion MCP for AI tools like ChatGPT, Claude, and Cursor. +The supported MCP surface includes: + +- Search and fetch: `notion-search`, `notion-fetch` +- Pages: `notion-create-pages`, `notion-update-page`, `notion-move-pages`, `notion-duplicate-page` +- Databases and data sources: `notion-create-database`, `notion-update-data-source`, `notion-query-data-sources` +- Views: `notion-create-view`, `notion-update-view`, `notion-query-database-view` +- Comments: `notion-create-comment`, `notion-get-comments` +- Identity: `notion-get-teams`, `notion-get-users`, `notion-get-user`, `notion-get-self` + +The Notion API also covers pages, blocks, databases, data sources, users, views, file uploads, comments, search, authentication, and link previews. + +Use Notion MCP when the agent is connected directly to Notion from an AI environment. Use `ntn` when you want a CLI workflow, public API inspection, or worker management. Use `ntn api ls` if you want a quick inventory of supported endpoints. -## Dosu CLI setup +## Dosu docs surface -- `dosu login` to authenticate. -- `dosu status` to confirm account and MCP configuration. -- `dosu mcp add codex -g` to register the MCP target for Codex-compatible tools. +The official Dosu docs (`docs.dosu.dev`) cover: -## Notion CLI workflow +- Deployment +- Data sources +- Interactions +- Public spaces +- Auto-labeling +- Issue triage and Q&A +- Generate docs +- Maintain docs +- GitHub, Slack, and Confluence installation/configuration +- RBAC +- MCP +- Single sign-on (SSO) -- Use `ntn` for Notion API tasks, worker operations, page updates, and database queries. -- Start with `ntn --help`, `ntn api --help`, `ntn workers --help`, and `ntn login` when setting up a session. -- If an `ntn api` subcommand cannot load its spec, retry after `ntn login` or confirm the target workspace is reachable. -- Keep Notion work separate from repo code changes unless the task explicitly requires both. +That means Dosu is useful both as a documentation/search system and as an MCP integration point for agents. ## Shared rules +- Prefer official help/docs over memory. - Prefer links over duplicated guidance. -- Keep task-specific procedures in the specialized playbooks. -- Save knowledge only when it will stay useful across future tasks. -- When a finding is specific to OpenShelf, include the repo name plus the relevant file paths in the saved topic. +- Save only stable, reusable knowledge. +- When saving an OpenShelf-specific topic, include the repo name and the relevant file paths. diff --git a/instruction.md b/instruction.md index 9b7c8aaf..ebf38160 100644 --- a/instruction.md +++ b/instruction.md @@ -142,7 +142,7 @@ E2E tests skip real GitHub OAuth by calling `/api/auth/test-token` (only active Use the shared docs instead of restating detailed workflows here: - `AGENTS.md` — universal entry point for any agent -- `docs/agent-tooling.md` — Dosu / Notion / ntn workflow +- `docs/agent-tooling.md` — Dosu / Notion / ntn reference, including CLI and MCP usage - `.github/agents/pr-review-closure-loop.md` — review-thread closure loop - `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow From 2c01043fc010ec38f2f0d91c20f79f652cc0dbe0 Mon Sep 17 00:00:00 2001 From: is0692vs Date: Tue, 14 Apr 2026 10:10:51 +0900 Subject: [PATCH 3/4] docs: fix agent-doc relative paths and workflow guidance --- .github/copilot-instructions.md | 26 ++++++++++++++------------ docs/agent-tooling.md | 6 +----- instruction.md | 2 ++ 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 521a8eb0..966d946d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -9,13 +9,13 @@ applyTo: "**" ## Agent entry points -If you only need one starting point, open `AGENTS.md`. +If you only need one starting point, open `../AGENTS.md`. -- `AGENTS.md` — universal index for every agent -- `docs/agent-tooling.md` — shared Dosu / Notion / ntn reference, including CLI, MCP, and knowledge capture rules -- `.github/agents/pr-review-closure-loop.md` — PR review conversation closure loop -- `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow -- `instruction.md` — legacy guide kept for compatibility +- `../AGENTS.md` — universal index for every agent +- `../docs/agent-tooling.md` — shared Dosu / Notion / ntn reference, including CLI, MCP, and knowledge capture rules +- `./agents/pr-review-closure-loop.md` — PR review conversation closure loop +- `./agents/pr-consolidation-playbook.md` — PR consolidation workflow +- `../instruction.md` — legacy guide kept for compatibility ## Quick Reference @@ -267,8 +267,8 @@ Run `npm run typecheck` before committing to catch TS errors. ### PR Review Playbooks -- Detailed review-thread closure: `.github/agents/pr-review-closure-loop.md` -- Detailed PR consolidation: `.github/agents/pr-consolidation-playbook.md` +- Detailed review-thread closure: `./agents/pr-review-closure-loop.md` +- Detailed PR consolidation: `./agents/pr-consolidation-playbook.md` - Use those playbooks as the source of truth for reply/resolve loops and absorbed-PR handling. --- @@ -349,7 +349,7 @@ See `apps/web/README.md` and `apps/api/wrangler.toml` for environment variable r ## Notes for Agents -- Always check `AGENTS.md` **first** for shared agent workflow, then this file for project-specific conventions. +- Always check `../AGENTS.md` **first** for shared agent workflow, then this file for project-specific conventions. - Use `npm run typecheck` and `npm run test` to validate changes before pushing. - E2E tests require both `apps/api` and `apps/web` running; Playwright auto-starts them. - For database changes, test locally with `db:migrate:local` before planning remote migrations. @@ -362,6 +362,8 @@ See `apps/web/README.md` and `apps/api/wrangler.toml` for environment variable r ### PR Workflow Reminders -- Use `.github/agents/pr-review-closure-loop.md` for the full review / CI loop. -- Use `.github/agents/pr-consolidation-playbook.md` for PR consolidation. -- Keep `staging` as the first merge target for feature work. +- Use `./agents/pr-review-closure-loop.md` for the full review / CI loop. +- Use `./agents/pr-consolidation-playbook.md` for PR consolidation. +- Never commit directly to `main`; always work on a feature branch via PR. +- Keep `staging` as the first merge target for feature work, and retarget PRs to `staging` when automation or maintainer guidance requests it. +- If `main` and `staging` diverge, use the repository main→staging sync PR automation (`npm run pr:sync-main-to-staging`) before promotion work. diff --git a/docs/agent-tooling.md b/docs/agent-tooling.md index 622d2319..9000cfd6 100644 --- a/docs/agent-tooling.md +++ b/docs/agent-tooling.md @@ -6,11 +6,7 @@ Use it when you need to choose between Dosu, Notion CLI (`ntn`), or the Notion/D ## Entry points -- `AGENTS.md` — universal index for any agent -- `.github/copilot-instructions.md` — OpenShelf repository conventions and coding workflow -- `.github/agents/pr-review-closure-loop.md` — review-thread closure loop -- `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow -- `instruction.md` — legacy guide kept for compatibility +See [`AGENTS.md`](../AGENTS.md) for the full index of agent entry points. ## What to use when diff --git a/instruction.md b/instruction.md index ebf38160..5d2e0b48 100644 --- a/instruction.md +++ b/instruction.md @@ -146,6 +146,8 @@ Use the shared docs instead of restating detailed workflows here: - `.github/agents/pr-review-closure-loop.md` — review-thread closure loop - `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow +### Branch Workflow + - New feature or task: create a branch from the default branch and open a Pull Request. - Improving an existing PR or branch: check out the existing feature branch and push your changes. From 87e8c95511f82c11622420498e1939e306e6c444 Mon Sep 17 00:00:00 2001 From: is0692vs Date: Tue, 14 Apr 2026 14:42:47 +0900 Subject: [PATCH 4/4] docs: refine agent tooling guidance --- .github/copilot-instructions.md | 2 +- AGENTS.md | 2 +- README.md | 2 +- docs/agent-tooling.md | 129 ++++++++++++++++++-------------- instruction.md | 2 +- 5 files changed, 77 insertions(+), 60 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 966d946d..ef124b8b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -12,7 +12,7 @@ applyTo: "**" If you only need one starting point, open `../AGENTS.md`. - `../AGENTS.md` — universal index for every agent -- `../docs/agent-tooling.md` — shared Dosu / Notion / ntn reference, including CLI, MCP, and knowledge capture rules +- `../docs/agent-tooling.md` — canonical OpenShelf reference for Dosu / Notion / ntn usage, including CLI, MCP, and knowledge capture rules - `./agents/pr-review-closure-loop.md` — PR review conversation closure loop - `./agents/pr-consolidation-playbook.md` — PR consolidation workflow - `../instruction.md` — legacy guide kept for compatibility diff --git a/AGENTS.md b/AGENTS.md index 71b39071..138d3e27 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ This is the universal entry point for agents working in OpenShelf. Start here: -- `docs/agent-tooling.md` — shared Dosu / Notion / ntn reference, including CLI, MCP, and knowledge-capture rules +- `docs/agent-tooling.md` — canonical OpenShelf reference for Dosu / Notion / ntn usage, including CLI, MCP, and knowledge-capture rules - `.github/copilot-instructions.md` — OpenShelf repository conventions and coding workflow - `.github/agents/pr-review-closure-loop.md` — PR review conversation closure loop - `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow diff --git a/README.md b/README.md index 7efa7c72..1cc3724c 100644 --- a/README.md +++ b/README.md @@ -227,7 +227,7 @@ cd apps/e2e && npx playwright test ## 🤖 エージェント向けドキュメント - [`AGENTS.md`](./AGENTS.md) — どのエージェントでも最初に読む共通入口 -- [`docs/agent-tooling.md`](./docs/agent-tooling.md) — Dosu / Notion / ntn の共通参照（CLI / MCP / 知識保存） +- [`docs/agent-tooling.md`](./docs/agent-tooling.md) — OpenShelf における Dosu / Notion / ntn の正本ドキュメント（CLI / MCP / 知識保存） - [`.github/copilot-instructions.md`](./.github/copilot-instructions.md) — OpenShelf 固有の開発ルール --- diff --git a/docs/agent-tooling.md b/docs/agent-tooling.md index 9000cfd6..a0454387 100644 --- a/docs/agent-tooling.md +++ b/docs/agent-tooling.md @@ -1,8 +1,8 @@ # Agent Tooling and Knowledge Workflow -This is the canonical reference for Copilot, Codex, and other agents working in OpenShelf. +This is the canonical OpenShelf reference for agents choosing between Dosu, Notion CLI (`ntn`), and the Notion or Dosu MCP surfaces. -Use it when you need to choose between Dosu, Notion CLI (`ntn`), or the Notion/Dosu MCP surfaces. +Use this document for repo-specific workflow guidance. If your machine also has a shared home-level Dosu bundle installed, treat that as a local setup companion rather than the OpenShelf source of truth. ## Entry points @@ -12,17 +12,19 @@ See [`AGENTS.md`](../AGENTS.md) for the full index of agent entry points. | Need | Prefer | Why | | --- | --- | --- | -| Find repo or cross-cutting context | `dosu-init_knowledge` | Starts with knowledge discovery instead of guessing. | -| Search docs or runbooks broadly | `dosu-search_documentation` | Good for discovering relevant sources. | -| Read exact source text | `dosu-fetch_source` | Best when wording, lines, or citations matter. | -| Ask for a cited synthesis | `dosu-ask` | Use after you have enough sources. | -| Preserve a stable finding | `dosu-save_topic` | Captures reusable knowledge for later tasks. | -| Work with Notion pages, databases, files, or workers | `ntn` | CLI for workspace operations and worker management. | -| Wire Dosu into an AI tool | `dosu setup` / `dosu mcp add` | Registers Dosu MCP for the current environment. | +| Build a first-pass mental model of the repo or an unfamiliar subsystem | `init_knowledge` | Starts from existing knowledge instead of guessing. | +| Search docs, runbooks, or policy pages broadly | `search_documentation` | Good for discovering candidate sources before reading details. | +| Read exact source text with citations or line ranges | `fetch_source` | Best when wording, line references, or precise excerpts matter. | +| Target a specific indexed repo or workspace before synthesis | `list_available_data_sources` | Helps keep `ask` focused on the right source set. | +| Ask for a cited synthesis across one or more indexed sources | `ask` | Best after you know the relevant sources or question scope. | +| Preserve a stable finding for future work | `save_topic` | Captures reusable knowledge for later tasks. | +| Research a supported public OSS repository | `find_public_library` -> `ask_public_library` | Finds the supported slug first, then asks a cited question. | +| Work with Notion pages, databases, files, or workers from the shell | `ntn` | Best for direct CLI workflows and worker lifecycle commands. | +| Wire Dosu into an AI tool locally or globally | `dosu setup` / `dosu mcp add` | Registers Dosu MCP for the current environment. | ## Dosu CLI -`dosu --help` shows: +`dosu --help` currently exposes: - `login` - `logout` @@ -31,7 +33,7 @@ See [`AGENTS.md`](../AGENTS.md) for the full index of agent entry points. - `setup` - `logs` -Use the Dosu CLI when you are configuring access or MCP integration, not when you are searching content. +Use the Dosu CLI when you are configuring access or MCP integration, not when you are retrieving knowledge. Helpful commands: @@ -39,36 +41,41 @@ Helpful commands: dosu status dosu login dosu setup [--deployment ] -dosu mcp add [-g] dosu mcp list +dosu mcp add [-g] +dosu logs ``` Notes: -- `dosu setup` sets up Dosu MCP for AI tools. -- `dosu mcp add -g` adds the integration globally instead of project-local. +- `dosu setup` bootstraps Dosu MCP for supported AI tools. +- `dosu mcp add -g` installs the integration globally instead of project-local. +- `dosu mcp list` is the fastest way to confirm which tool names are supported on the current machine. - `dosu status` confirms whether you are logged in and which deployment is active. - `dosu logs` is the place to look when the integration needs debugging. ## Dosu knowledge workflow -1. Start with `dosu-init_knowledge` for unfamiliar or cross-cutting work. -2. Use `dosu-search_documentation` to find candidate sources. -3. Use `dosu-fetch_source` for exact source text. -4. Use `dosu-ask` for a cited answer once you have enough context. -5. Use `dosu-save_topic` when the finding is durable and reusable. +1. Start with `init_knowledge` for unfamiliar, cross-cutting, or exploratory work. +2. Use `search_documentation` to find raw docs and runbooks that may not yet be promoted into curated knowledge. +3. Use `fetch_source` for exact source text, and prefer narrow line ranges. +4. Before `ask`, run `list_available_data_sources` unless you already know the relevant source IDs. +5. Use `ask` for a cited answer once the question and source scope are clear. +6. Use `save_topic` only when the finding is durable, reusable, and no longer just in-progress investigation. -Other useful Dosu tools: +OpenShelf rule of thumb: -- `dosu-list_available_data_sources` -- `dosu-find_public_library` -- `dosu-ask_public_library` +- Repo-specific data source IDs, prompt recipes, and operational gotchas belong in repo docs or saved topics, not in a generic home-level setup note. -Use Dosu knowledge tools when the task is about repo understanding, a shared runbook, a cross-file dependency, or a fact that should be reused later. +When saving an OpenShelf topic, include: + +- the repository name +- the relevant file paths +- the operational lesson that should still matter in future runs ## Notion CLI (`ntn`) -`ntn --help` shows: +`ntn --help` currently exposes: - `api` — public Notion API, beta - `files` — file uploads, beta @@ -78,6 +85,23 @@ Use Dosu knowledge tools when the task is about repo understanding, a shared run - `update` - `workers` +`ntn workers --help` currently exposes: + +- `capabilities` +- `create` +- `delete` +- `deploy` +- `new` +- `env` +- `exec` +- `get` +- `oauth` +- `list` +- `runs` +- `sync` +- `webhooks` +- `tui` + Helpful commands: ```bash @@ -95,11 +119,11 @@ ntn workers exec --data '{...}' Notes: -- `ntn api ls` reads the live OpenAPI index and does not require authentication. - `ntn api` is the best way to inspect the public Notion API surface from the CLI. -- `ntn pages` currently focuses on creating pages from Markdown content. +- `ntn api ls` depends on the live OpenAPI spec and may fail temporarily if that spec cannot be fetched. +- `ntn pages` focuses on creating pages from Markdown content. - `ntn files` handles file uploads and retrieval. -- `ntn workers` manages deploy, list, exec, env, oauth, runs, sync, webhooks, and the TUI. +- `ntn workers` covers worker deployment, execution, environment variables, OAuth, runs, sync, webhooks, and the TUI. Common environment variables: @@ -109,46 +133,39 @@ Common environment variables: - `NOTION_ENV` - `NOTION_HOME` -Use `ntn` when you need to operate on Notion content directly or when you need worker lifecycle commands. +Use `ntn` when you need to operate on Notion content directly, inspect the public API from the shell, or manage worker lifecycle commands. ## Notion MCP / API -Notion docs describe Notion MCP for AI tools like ChatGPT, Claude, and Cursor. -The supported MCP surface includes: +Notion provides MCP support for AI tools like ChatGPT, Claude, and Cursor. Exact tool names can vary by environment, but the typical surface includes: -- Search and fetch: `notion-search`, `notion-fetch` -- Pages: `notion-create-pages`, `notion-update-page`, `notion-move-pages`, `notion-duplicate-page` -- Databases and data sources: `notion-create-database`, `notion-update-data-source`, `notion-query-data-sources` -- Views: `notion-create-view`, `notion-update-view`, `notion-query-database-view` -- Comments: `notion-create-comment`, `notion-get-comments` -- Identity: `notion-get-teams`, `notion-get-users`, `notion-get-user`, `notion-get-self` +- search and fetch +- page create, update, move, and duplicate +- database and data source create or update +- view create, update, and query +- comments and discussion threads +- users, teams, and workspace identity -The Notion API also covers pages, blocks, databases, data sources, users, views, file uploads, comments, search, authentication, and link previews. - -Use Notion MCP when the agent is connected directly to Notion from an AI environment. Use `ntn` when you want a CLI workflow, public API inspection, or worker management. Use `ntn api ls` if you want a quick inventory of supported endpoints. +Use Notion MCP when the agent is already connected directly to Notion from an AI environment. Use `ntn` when you want a CLI workflow, worker management, or public API inspection from the shell. ## Dosu docs surface -The official Dosu docs (`docs.dosu.dev`) cover: - -- Deployment -- Data sources -- Interactions -- Public spaces -- Auto-labeling -- Issue triage and Q&A -- Generate docs -- Maintain docs -- GitHub, Slack, and Confluence installation/configuration -- RBAC +The official Dosu docs ([docs.dosu.dev](https://docs.dosu.dev/)) cover: + +- deployment and channels +- data sources - MCP -- Single sign-on (SSO) +- issue triage and Q&A +- generated and maintained docs +- GitHub, Slack, and Confluence integrations +- RBAC +- SSO -That means Dosu is useful both as a documentation/search system and as an MCP integration point for agents. +That means Dosu is useful both as a documentation and search system and as an MCP integration point for agents. ## Shared rules -- Prefer official help/docs over memory. +- Prefer official help output and official docs over memory. - Prefer links over duplicated guidance. - Save only stable, reusable knowledge. -- When saving an OpenShelf-specific topic, include the repo name and the relevant file paths. +- Keep machine-specific setup in home-level docs and OpenShelf-specific rules in this repo. diff --git a/instruction.md b/instruction.md index 5d2e0b48..a190747a 100644 --- a/instruction.md +++ b/instruction.md @@ -142,7 +142,7 @@ E2E tests skip real GitHub OAuth by calling `/api/auth/test-token` (only active Use the shared docs instead of restating detailed workflows here: - `AGENTS.md` — universal entry point for any agent -- `docs/agent-tooling.md` — Dosu / Notion / ntn reference, including CLI and MCP usage +- `docs/agent-tooling.md` — canonical OpenShelf reference for Dosu / Notion / ntn usage, including CLI and MCP guidance - `.github/agents/pr-review-closure-loop.md` — review-thread closure loop - `.github/agents/pr-consolidation-playbook.md` — PR consolidation workflow