ADR Drafter

Draft a policy record, not an implementation memo.

Read

1. dev-docs/agents/adr-governance.md
2. dev-docs/agents/adr-criteria.md
3. dev-docs/agents/adr-workflow.md
4. dev-docs/adr/template.md
5. Related ADRs under dev-docs/adr/

Workflow

1. Confirm whether the target is a new ADR or an update to an existing ADR.
2. Read the issue, diff, relevant specs, tests, and implementation files.
3. Extract:
   • policy-level context
   • chosen decision
   • positive and negative consequences
   • concrete evidence from tests, code, and related specs
4. Produce one of these outputs:
   • a new ADR draft
   • an update proposal for an existing ADR
   • ADR not needed with rationale

Draft Rules

• Keep why in the ADR and leave detailed how in code or specs.
• Fill Tests, Code, and Related specs whenever possible.
• If the policy replaces an old one, state the supersede relation explicitly.
• If evidence is missing, say so instead of inventing support.

ADR Indexer

Refresh the derived ADR map after the source ADRs change.

Read

1. dev-docs/agents/adr-governance.md
2. dev-docs/agents/adr-workflow.md
3. dev-docs/specs/adr-index.md
4. All ADR files under dev-docs/adr/
5. Existing dev-docs/adr/README.md, dev-docs/adr/index.yaml, dev-docs/adr/decision-map.md

Workflow

1. Scan the ADR files and collect normalized metadata:
   • id
   • title
   • status
   • primary_domain
   • domains
   • supersedes
   • superseded_by
   • related_specs
2. Compare the normalized metadata with README.md, index.yaml, and decision-map.md.
3. Update the derived artifacts so that status, primary domain, domain grouping, and supersede relationships match the ADR source files.
4. Report any ambiguity that cannot be derived from the ADR text alone.

Output Contract

Return a concise summary with:

• updated artifacts
• added or changed ADR entries
• consistency findings

Treat ADR-xxxx-*.md as the source of truth. Do not invent domains, statuses, or supersede links that the ADR text cannot justify.

ADR Linter

Review the ADR as a decision record, not as prose polish.

Read

1. dev-docs/agents/adr-governance.md
2. dev-docs/agents/adr-workflow.md
3. dev-docs/adr/template.md
4. Related ADRs if the draft mentions supersede or overlap

Workflow

1. Validate the status value.
2. Check that the ADR has 状態, 背景, 決定, 影響, 根拠, Supersedes, and Superseded by.
3. Verify that 根拠 contains concrete Tests, Code, or Related specs.
4. Check that consequences include tradeoffs, not only benefits.
5. If supersede or replacement is claimed, verify the referenced ADR links are present and consistent.

Output Contract

Return findings first, ordered by severity.

• high: contract hole, missing decision, invalid status, missing supersede linkage
• medium: weak context, weak evidence, one-sided consequences
• low: clarity or consistency issues

If no findings exist, say that explicitly and mention any residual review risk.

ADR Reconciler

Audit the current decision records before proposing new text.

Read

1. dev-docs/agents/adr-governance.md
2. dev-docs/agents/adr-workflow.md
3. dev-docs/specs/adr-index.md
4. Target ADRs under dev-docs/adr/
5. Related files under dev-docs/specs/, tests/, and src/

Workflow

1. Select the target ADRs from changed domains, explicit ADR IDs, or related index entries.
2. Read each ADR claim and the linked specs, tests, and implementation paths.
3. Build an evidence matrix for every finding:
   • adr
   • specs
   • src
   • tests
4. Classify findings as one of:
   • policy-drift
   • missing-adr-update
   • missing-evidence
   • stale-reference
5. Recommend the next action:
   • update-adr
   • new-adr
   • update-specs
   • add-tests
   • no-action

Output Contract

Return a concise audit result with:

• scope
  • adrs
  • specs
  • src
  • tests
• findings

Each finding should include:

• type
• severity
• claim
• affected ADRs
• evidence matrix
  • adr
  • specs
  • src
  • tests
• recommended action

Do not silently rewrite ADR text. If the finding implies a new or changed policy, route back through adr-suggester and adr-drafter.

ADR Reviewer

Review the policy decision, not just the document shape.

Read

1. dev-docs/agents/adr-governance.md
2. dev-docs/agents/adr-criteria.md
3. dev-docs/agents/adr-workflow.md
4. dev-docs/specs/adr-review.md
5. The target ADR draft
6. Related ADRs, relevant public docs under docs/ when public API / CLI / MCP contracts are in scope, internal specs, tests, src paths, and issue / PR context
7. Existing adr-linter findings for the current draft

Workflow

1. Confirm the current draft has no unresolved adr-linter high / medium findings. Only proceed with design review after that precondition is met.
2. Read the ADR draft and identify the single policy question it is trying to resolve.
3. Check whether the draft overlaps with, contradicts, or should supersede an existing ADR or spec.
4. Verify that the cited Tests, Code, and Related specs actually support the claims being made, and include relevant public docs/ pages in scope when the ADR touches public API / CLI / MCP contracts.
5. Review whether compatibility, rollout, fallback, migration, or safety consequences are covered when relevant.
6. Detect human-owned decisions that AI should not settle, including public API break judgment, security or license calls, major directory reorganization, or unresolved product/spec direction.
7. Return one verdict:
   • ready
   • revise
   • escalate

Output Contract

Return findings first, ordered by severity, and include:

• verdict
• scope
  • draft
  • related ADRs
  • public docs
  • specs
  • src
  • tests
  • issue / PR context
• findings

Each finding should include:

• type
  • decision-gap
  • scope-conflict
  • evidence-risk
  • rollout-gap
  • ownership-escalation
• severity
• summary
• why it matters
• suggested revision
• evidence
  • draft
  • related sources

Also include top-level:

• open questions
• residual risks

Do not silently rewrite the ADR text. If the review hits a human-owned decision, return escalate instead of inventing a final policy.

ADR Suggester

Classify the change before drafting anything.

Read

1. dev-docs/agents/adr-criteria.md
2. dev-docs/agents/adr-governance.md
3. Relevant files under dev-docs/adr/

Workflow

1. Read the issue, PR, diff, or review comment that introduced the change.
2. Read the relevant specs, implementation path, tests, and existing ADRs needed to justify the verdict.
3. Map the change to one or more ExStruct design domains.
4. Assemble an evidence triad:
   • specs contract
   • src symbol or execution path
   • tests that fix the current behavior, or an explicit note that evidence is missing
5. Return one verdict:
   • required
   • recommended
   • not-needed
6. If verdict is not not-needed, propose:
   • a candidate ADR title
   • existing ADRs to inspect or update
   • whether the next step is new-adr or update-existing-adr

Output Contract

Return a concise result with:

• verdict
• rationale
• affected domains
• existing ADR candidates
• suggested next action
• evidence triad
  • specs
  • src
  • tests

Do not draft the ADR body.

Codacy Issues Fetcher

Run scripts/codacy_issues.py as the primary interface to Codacy issue retrieval. Avoid reimplementing API calls unless the script itself must be changed.

Workflow

1. Confirm prerequisites.

• Run from repository root so scripts/codacy_issues.py is reachable.
• Ensure CODACY_API_TOKEN is set and valid.
• Prefer explicit org and repo if user provides them; otherwise rely on Git origin auto-detection.

2. Choose scope and severity.

• Repository scope: omit --pr.
• Pull request scope: pass --pr <number>.
• Severity filter (--min-level): Error, High, Warning, Info.
• Provider (--provider): gh, gl, bb (default is effectively gh).

3. Run one of the command patterns.

# Repository issues (explicit target)
python scripts/codacy_issues.py <org> <repo> --provider gh --min-level Warning

# Pull request issues (explicit target)
python scripts/codacy_issues.py <org> <repo> --pr <number> --provider gh --min-level Warning

# Pull request issues (auto-detect org/repo from git origin)
python scripts/codacy_issues.py --pr <number> --min-level Warning

4. Parse output JSON and respond with actionable summary.

• Trust payload fields: scope, organization, repository, pullRequest, minLevel, total, issues.
• issues entries are formatted as: <level> | <file_path>:<line_no> | <rule> | <category> | <message>
• Report high-severity findings first, then summarize counts.

Error Handling

• HTTP 401 / Unauthorized: token invalid or missing permissions. Ask user to set or refresh CODACY_API_TOKEN.
• CODACY_API_TOKEN is not set: export the environment variable before retrying.
• Invalid --provider: use only gh, gl, or bb.
• Segment validation errors (Invalid org/repo/pr): sanitize input and rerun.

Output Policy

• Return concise triage-ready results, not raw command logs.
• Include the exact command you used when reproducibility matters.
• If no issues match the selected --min-level, state that explicitly.

ExStruct CLI

Use the existing editing CLI as the default local operational interface for ExStruct workbook create/edit requests.

Select a command

• Use exstruct make when the user wants a new workbook created and populated.
• Use exstruct patch when the user wants an existing workbook edited.
• Use exstruct validate when workbook readability is uncertain or before a risky edit on an unfamiliar file.
• Use exstruct ops list when the required operation is still unclear.
• Use exstruct ops describe <op> when you know the likely op name but need the exact schema or constraints.
• Hand the workflow off to MCP when the user needs host-owned path policy, transport mapping, artifact mirroring, or other server-managed behavior.

Safety rules

• Do not invent unsupported patch ops.
• Do not apply destructive edits immediately when the request is ambiguous.
• Prefer --dry-run before risky edits.
• Pin --backend openpyxl when the dry run and the real apply must use the same engine.
• Explain backend-specific failures directly instead of hiding them behind a generic retry.

Workflow

1. Decide whether the request is create, edit, or actually an MCP-hosted task.
2. Identify the needed op or inspect the public op schema.
3. Validate the workbook when the file, backend, or request is uncertain.
4. Run --dry-run for risky edits and inspect PatchResult.
5. Apply the real edit only after the planned change is acceptable.
6. Verify the result with the lightest step that still matches the user's risk.

References

• references/command-selection.md
• references/safe-editing.md
• references/ops-guidance.md
• references/verify-workflows.md
• references/backend-constraints.md