Hiroki-org · is0692vs · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026
diff --git 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
@@ -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
@@ -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` — 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
+
 ## 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 <PR#> --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: <subject>"
-     git push
-     ```
-   - Reply to the conversation explaining the fix:
-     ```bash
-     gh pr comment <PR#> --body "✅ Applied in commit $(git rev-parse --short HEAD). Changes: <brief description>"
-     ```
-   - Mark as resolved on GitHub (via web UI or after approval)
-
-   **Path B: Declining or deferring**
-   - Reply with justification:
-     ```bash
-     gh pr comment <PR#> --body "⚠️ Deferred for future work because: <reason>. 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 <PR#> --json reviews | grep -i "pending\|unresolved"
-   ```
-
-   Status should be empty (no pending reviews).
-
-4. **Check CI status**
-
-   ```bash
-   gh pr checks <PR#>
-   ```
-
-   - **All passing?** → Proceed to merge
-   - **Any failing?** → Investigate and fix:
-     ```bash
-     gh pr checks <PR#> --watch  # Real-time logs
-     ```
-
-5. **Final approval and merge**
-
-   ```bash
-   # Wait for any last-minute feedback
-   sleep 300 && gh pr checks <PR#>
-
-   # If all checks pass and reviews approved:
-   gh pr merge <PR#> --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: `./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.
 
 ---
 
@@ -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,8 @@ 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 <PR#> --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 <PR#>` to let CI run before final checks.
+- 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/AGENTS.md 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` — 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
+- `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
@@ -224,6 +224,14 @@ cd apps/e2e && npx playwright test
 
 ---
 
+## 🤖 エージェント向けドキュメント
+
+- [`AGENTS.md`](./AGENTS.md) — どのエージェントでも最初に読む共通入口
+- [`docs/agent-tooling.md`](./docs/agent-tooling.md) — OpenShelf における Dosu / Notion / ntn の正本ドキュメント（CLI / MCP / 知識保存）
+- [`.github/copilot-instructions.md`](./.github/copilot-instructions.md) — OpenShelf 固有の開発ルール
+
+---
+
 ## 📄 ライセンス
 
 [MIT License](./LICENSE)
diff --git a/docs/agent-tooling.md b/docs/agent-tooling.md
@@ -0,0 +1,171 @@
+# Agent Tooling and Knowledge Workflow
+
+This is the canonical OpenShelf reference for agents choosing between Dosu, Notion CLI (`ntn`), and the Notion or 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
+
+See [`AGENTS.md`](../AGENTS.md) for the full index of agent entry points.
+
+## What to use when
+
+| Need | Prefer | Why |
+| --- | --- | --- |
+| 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` currently exposes:
+
+- `login`
+- `logout`
+- `status`
+- `mcp`
+- `setup`
+- `logs`
+
+Use the Dosu CLI when you are configuring access or MCP integration, not when you are retrieving knowledge.
+
+Helpful commands:
+
+```bash
+dosu status
+dosu login
+dosu setup [--deployment <id>]
+dosu mcp list
+dosu mcp add [-g] <tool>
+dosu logs
+```
+
+Notes:
+
+- `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 `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.
+
+OpenShelf rule of thumb:
+
+- 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.
+
+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` currently exposes:
+
+- `api` — public Notion API, beta
+- `files` — file uploads, beta
+- `pages`
+- `login`
+- `logout`
+- `update`
+- `workers`
+
+`ntn workers --help` currently exposes:
+
+- `capabilities`
+- `create`
+- `delete`
+- `deploy`
+- `new`
+- `env`
+- `exec`
+- `get`
+- `oauth`
+- `list`
+- `runs`
+- `sync`
+- `webhooks`
+- `tui`
+
+Helpful commands:
+
+```bash
+ntn api ls
+ntn api <path> --help
+ntn api <path> --docs
+ntn api <path> --spec
+ntn pages create --content '# Title\n\nBody'
+ntn files create < file.png
+ntn files get <upload-id>
+ntn files list
+ntn workers list
+ntn workers exec <KEY> --data '{...}'
+```
+
+Notes:
+
+- `ntn api` is the best way to inspect the public Notion API surface from the CLI.
+- `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` covers worker deployment, execution, environment variables, 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, inspect the public API from the shell, or manage worker lifecycle commands.
+
+## Notion MCP / API
+
+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
+- 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
+
+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](https://docs.dosu.dev/)) cover:
+
+- deployment and channels
+- data sources
+- MCP
+- 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 and search system and as an MCP integration point for agents.
+
+## Shared rules
+
+- Prefer official help output and official docs over memory.
+- Prefer links over duplicated guidance.
+- Save only stable, reusable knowledge.
+- Keep machine-specific setup in home-level docs and OpenShelf-specific rules in this repo.
diff --git a/instruction.md b/instruction.md
@@ -139,28 +139,17 @@ 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` — 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
 
-### Agent Playbooks
+### Branch Workflow
 
-- [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.