codepatrol

Directing the Security Investigation

Investigate the repository source code from a security perspective area by area, and assemble the reports. When requested by the user, triage the issues in the assembled reports, automatically fix the issues, and reflect the status of the pull requests that fix the issues on the page. This session acts as the director. It interacts with the user, decides the areas to investigate, delegates the work to subagents, and verifies and records the results. This is the same even when there is only one area to investigate.

The behavior as the director is to load thekuden:orchestrator skill and follow its standards. The director does not read the code under investigation.

The work is delegated to subagents that execute the following skills.

skill	Work	What to read
codepatrol-setup	Generate and update the investigation target list and the perspective list	Code
codepatrol-report	Investigate one area and output a report	Code
codepatrol-triage	Classify the issues in the reports and create a triage page	Report
codepatrol-sync-state	Reflect the status of the pull requests that fix the issues on the page	Report and pull request
codepatrol-autofix	Fix one issue and finish the pull request	Report and code
codepatrol-autofix-deploynote	Summarize what to do before and after deployment in a comment on the release pull request	pull request

For subagents, specify a model of the Opus tier or above.

File Structure

.dev/codepatrol/
  config.md            ← レポートの書き出し先設定
  checklist.md         ← リポジトリ固有の機構と観点の補足。マスターのCHECKLIST.mdと一緒に読む
  targets.md           ← 調査対象リスト。各H2見出しが調査領域。関連リポジトリの一覧もヘッダにある
  {領域名}-{YYYY-MM-DD}.md  ← 領域ごとの調査レポート（書き出し先がローカルの場合）

Related Repositories

Bundle multiple repositories that make up the same service into one .dev/codepatrol/ and one hub page for investigation. There is one repository where the configuration is placed, and the other repositories are listed as related repositories in the header of the targets.md . Distinguish repositories by the area name prefix. On the related repository side, do not create .dev/codepatrol/ , and launch from the repository where the configuration is placed.

The clone location of related repositories differs for each developer, so it is not written in targets.md . If it is in memory, use that; if not, ask the user and record it in memory so that you do not have to ask on the next launch. For subagents, convey it as an absolute path for each repository.

Checking the Execution Environment

If any of the conditions are not met, do nothing, report the unmet conditions to the user, and stop. When only performing triage and status synchronization, conditions 2 and 3 do not need to be checked:

Your model is of the Opus tier or above (Opus, Fable, Mythos, etc.). Lower tiers such as Sonnet and Haiku do not have sufficient issue detection capability
Codex CLI is installed. Use the Bash tool to run command -v codex to verify
The Codex model is a flagship model of Sol or higher (Sol, Astra, etc.), and reasoning effort is medium or higher. Write a short prompt to a file outside the working tree, and pass it tocodex exec --ephemeral via stdin, run it once, and read from the output header. Lightweight tiers such as Luna and Terra, and models from generations before Sol, are insufficient as discussion partners

codex exec Run directly only for this check. Consult Codex by having the subagent call codex-consultation with the Skill tool.

Working tree for investigation

Investigation and list generation/updating are done in a git worktree with the investigation branch checked out. Investigation takes a long time, so during that time the user can continue other work in their own checkout.

The investigation branch is cut from the latest default branch. If an investigation worktree created by a previous session remains, use it and make it follow the latest default branch
Related repositories are read-only, and no changes are accumulated. Prepare a place where the latest default branch state of each can be read without changing the user's checkout. Investigating with old code treats parts already fixed on the default branch as problems
In the user's checkout, do not switch branches or modify files

.dev/codepatrol/ The location of is determined by whether the repository manages this directory with git.

In repositories that manage it, use the one in the investigation worktree. When configuration files or reports are on a branch other than the default branch or in the user's checkout, carry them over to the investigation branch. If not carried over, the configuration will be recreated and already-investigated areas will be treated as uninvestigated
In repositories that do not manage it, such as by gitignoring it, use the one in the user's checkout. This is because it does not appear in the worktree. This directory is the only one that may be rewritten in the user's checkout. Do not commit

Once the working tree is prepared, report to the user. Make it possible for the user to grasp where the work is done and where changes remain.

The location of the investigation worktree and the branch name. Whether it was newly created or the one from the previous session is used
.dev/codepatrol/ The location of
The location for reading related repositories
When configuration files or reports are carried over, the source they were carried over from

Tell the subagent the location for reading the code of each repository and the location of.dev/codepatrol/ .

Setup

.dev/codepatrol/ If the three configuration files of are not all present, prepare the missing ones.

config.md

If not present, decide and record the report output destination.

Use the AskUserQuestion tool to ask the user for the output destination:
- Cosenseに集約する — Create the report as a Cosense page and aggregate it on the hub page via backlinks. Suitable for team sharing and discussion
- ローカルファイル — .dev/codepatrol/{領域名}-{YYYY-MM-DD}.md write to
For Cosense, confirm the project URL and hub page name (e.g., {プロダクト名} セキュリティレポート) with the user
Record in config.md. Format:

# Codepatrol Report Destination

レポートの書き出し先設定。

- 書き出し先: {Cosense または ローカル}
- project URL: {https://scrapbox.io/プロジェクト名}
- hubページ: {hubページ名}
- レポートページのタイトル規則: `{hubページ名} {YYYY/M/D} ({領域名})`
  - 年月日はレポート作成時点、月と日はゼロ埋めなし（例: 2026/7/3）
- 前提: cosense CLI（`npm install -g @helpfeel/cosense-cli`）のインストールとログイン

For local, record only "Output destination: Local".

If the existing config.md title convention differs from this form, tell the user. The user rewrites config.md.

Checking related repositories

targets.md On the first run when there is none, before entrusting codepatrol-setup, use the AskUserQuestion tool once to check whether there is another repository that makes up the same service. Typical examples are infrastructure configuration, another server handling uploads or delivery, billing services, and clients such as smartphone apps or browser extensions. Problems in another repository cannot be detected unless that repository is bundled in.

For each related repository to add, confirm the name and clone location, decide the area name prefix with the user, and include it in the instructions to codepatrol-setup
Client repositories are not subject to automatic detection. The perspective master also assumes the server side. When bundling, tell the user to manually add the area to targets.md and supplement perspectives with a repository-specific layer

Not only on the first run, tell the user about the "related repository candidates" in the codepatrol-setup report. For those decided to be added, decide the name, location, and prefix in the same way, and entrust codepatrol-setup with updating both files.

targets.md と checklist.md

In the following cases, launch a subagent that runs codepatrol-setup and entrust it with generation and updating.

The file does not exist
The user instructed an update
The user added or removed a related repository. Have both updated
Generated by From the record in, it cannot be confirmed that the generated model satisfies condition 1 of "Checking the execution environment". It is Sonnet, Haiku, Codex, no record, etc. Have both regenerated
Generated by From the record in, it cannot be confirmed that the reviewed Codex satisfies condition 3. There is a record of "Codex review not performed", the Codex execution environment is not written, the model is out of condition, etc. Have only the list review redone
Format The record in differs from or is missing the current value defined by "Configuration file format" incodepatrol-setup . This is when the format changed due to a skill update. Have both updated

Do not start an investigation with a list that has not gone through the Codex review in codepatrol-setup. If Codex stops and the review is not completed, report to the user and wait for their decision.

Before starting the investigation, read checklist.md and check thatchecklist and report responsibility boundaries does not contain descriptions that do not match. If there are assertions about problems, severity, or references to problems in the report, remove them before the investigation lead reads them. When code confirmation is needed to rewrite them as factual statements, entrust it to the subagent that runs codepatrol-setup.

From the subagent's report, tell the user the list of areas in targets.md. Splitting or merging areas is done by the user editing targets.md.

Decide which areas to investigate

targets.md Match the areas against existing reports, determine for each area whether it is uninvestigated or investigated, and if investigated, the time of the last investigation, and report this to the user.

If the output destination is Cosense: determine this from the titles of existing reports aggregated on the hub page. If there is no hub page or report, treat all areas as uninvestigated
If the output destination is local: .dev/codepatrol/ areas that have a report file are investigated. Read the investigation time from the date in the file name

Determine progress based only on the existence of reports and the investigation time. Do not infer whether reinvestigation is needed from the content of code changes.

If no scope is specified, confirm once with the AskUserQuestion tool. Whether to do only uninvestigated areas, whether to include reinvestigation of investigated areas, or whether to specify areas. When including reinvestigation, also confirm the cutoff time, i.e. areas that have only reports older than when should be reinvestigated. When restarted after an interruption, the remaining areas can be determined from the same cutoff.

The order is decided by the conductor.

Do uninvestigated areas first. Among those, prioritize areas named as the main responsible area by reports of other areas, and areas related to authorization, authentication, and external communication
For reinvestigation, start with areas whose last investigation is oldest

When restarted after an interruption, determine the remaining areas again from the scope and existing reports.

Delegate the investigation to a subagent

Launch a new subagent for each report and have it run codepatrol-report.

Things to include in the instructions

The name of the area in charge
For reinvestigation, the location of the existing report to treat as the previous one
The location to read the code for each repository, and the location of.dev/codepatrol/ location
The working directory. Under the session's temporary directory, separate it by area. This prevents Codex output and intermediate results from mixing with those of subagents running in parallel
The file listing problem names
Areas running in parallel, and areas whose files overlap with the area in charge

Do not include the content of existing problems in the instructions.

List of problem names

This is a file listing the problem names in existing reports, report by report. It prevents the same problem from being given different names across areas.

From the latest report of each area, pick up only the severity, heading, and name of each problem. Do not include the body of the problem
Create it before launching the first subagent, and recreate it each time one report is completed
The task of reading reports and creating the list may also be delegated to a subagent

Investigate in parallel

Parallelize only the set of areas whose files to read do not overlap. If you parallelize nearby areas, the same problem gets different names. As a guideline, run at most 3 in parallel. Even for areas in different repositories, paired areas have overlapping files. Use the paired areas written in targets.md as material for deciding the pairs.

When the parallelized set finishes, compare the "problems likely to overlap with other areas" in each subagent's report. If the same problem has been given different names, add one line to the corresponding problem in both reports, referencing the other's problem and stating which name will be treated as the single item.

Verify the subagent's report

Before reporting to the user, verify the following yourself.

The report has been output to the configured output destination
The consultation with Codex has completed through to the end. Verify this with the output left in the working directory
The consultation with Codex has been conducted through the procedure of the codex-consultation skill. When the record of the subagent's execution can be read, verify with the record; when it cannot be read, treat it as content based on the subagent's report

Record changes to configuration files

The subagent, during the work, checklist.md と targets.md edits. The subagent does not commit. The orchestrator verifies the diff and commits to the investigation branch..dev/codepatrol/ In repositories where is not managed with git, only verify the diff and do not commit.

Commit when setup is finished and each time one report is completed. When running in parallel, commit each time one set is finished
If the output destination is local, commit the report files as well
Before committing, read the diff.checklist.md If contains descriptions that do not fit the responsibility boundary, do not commit and remove them. The checklist is scaffolding for the investigation, and writing problems into it will steer the next investigation
Do not add the "perspectives/areas that should be added" reported by the subagent yourself. Tell the user, and for anything decided to be added, leave the update to the subagent that runs codepatrol-setup
Wait for the user's instructions for push and pull request creation. When finishing the work, report the name of the investigation branch and the commits accumulated to the user

Procedure

Have the first one investigate alone, report the result to the user, and wait for confirmation. After verifying that there are no problems with the report format and procedure, proceed to the remaining areas.

After that, report briefly each time one or one set is finished, and proceed to the next without waiting for approval. The report should include the report location, the number of problems and the breakdown by severity, the names and summaries of High problems, and whether there are items requiring verification in the actual environment.

Stop and wait for the user's judgment in the following cases.

Codex stopped, and the subagent was interrupted without outputting a report. Do not have the orchestrator conduct the investigation on its own behalf, nor switch to an investigation that does not use Codex
The report was not output to the configured export destination. Use the report that the subagent wrote to the working directory, and the commander redoes the output. If it still cannot be output, tell the user where the report is and stop. The working directory does not remain after the session ends, and the next time it is started, that area is treated as uninvestigated.
Between reports, there are discrepancies that the commander cannot decide.

Do not delete reports that have already been output.

Reports that have already been output are referenced by other reports and pull requests. Even when a mistake in the procedure is discovered later, do not delete or recreate them; report it to the user and wait for a decision.

Triage and state synchronization

Both are done when requested by the user. They are not work done on every investigation.

Only read and write reports and the triage page; do not read code and do not edit configuration files. Do not prepare a working tree for investigation.
This can be done only when the export destination is Cosense. The export destination and hub page are config.md , and the repository where the pull request to fix the problem is created is targets.md read from the related repositories in the header of . Only the header is read. Both read the one that represents the current investigation target. If there is something newer than the default branch in the investigation branch or the user's checkout, it is that one.

Triage

When there are many report problems, create material to decide which one is fixed by whom. Launch a subagent that runs codepatrol-triage.

Include in the instructions:

Hub page
Conditions for the problems to include. Include only when there is a user instruction.
The previous triage page. Find it from pages linked to the hub page.

From the subagent's report, tell the user the location of the created page, the number of lines by fix difficulty, and the problems whose fix difficulty was uncertain.

When there is a previous triage page, synchronize the state on the previous page before creating a new page. The lines for fix PRs are carried over as they are in the state of the previous page.

State synchronization

As fix work progresses, the state written on the page drifts from the actual state of the pull request. Launch a subagent that runs codepatrol-sync-state and fix the drift. Do this repeatedly while fix work continues.