name	improve-claude-agents
description	Improve or normalize repository agent policy docs (`CLAUDE.md`, `AGENTS.md`) using a balanced workflow: conditional planning, required verification, scoped subagent usage, and lightweight lessons capture. Use when users ask to tighten agent execution rules, convert rigid rules into practical gates, align CLAUDE/AGENTS policies, or audit existing workflow guidance.

Improve CLAUDE/AGENTS Policy

Use this workflow to update policy docs without making them rigid or verbose.

Workflow

Detect policy files and current state

Read CLAUDE.md and AGENTS.md if present.
If only one file exists, update it and create the missing counterpart only when the user asks for dual-file policy.

Apply balanced policy rules

Convert absolute rules ("always plan", "always use subagents") into conditional gates:
- Scope gate for simple vs complex work
- Required verification gate before completion
- Subagent usage only when parallel/context-heavy work benefits
Keep mandatory quality bars:
- No completion claims without evidence
- Test/build/lint or equivalent verification required
- Lessons capture only for reusable correction patterns

Keep policy compact and actionable

Prefer short, imperative bullets.
Avoid duplicate long blocks across files; either mirror concise content or keep one canonical and one pointer.
Keep task-specific procedures in task docs (tasks/todo.md) instead of expanding global policy files.

Validate before finishing

Confirm both files are consistent with the same workflow semantics.
Confirm no TODO placeholders remain.
Review diffs for overreach (policy-only change; no unrelated edits).

Required Policy Sections

When creating or normalizing policy docs, include these sections (exact names may vary):

Scope gate
Explore -> plan -> implement
Verification gate
Subagent strategy
Feedback/lessons loop
Context hygiene
Safety defaults

Output Contract

In the final response:

State which files changed.
Summarize policy behavior changes in 4-8 bullets.
Highlight any deliberately deferred item (for example, missing tasks/ directory).

Improve CLAUDE/AGENTS Policy

Use this workflow to update policy docs without making them rigid or verbose.

Workflow

Detect policy files and current state

Read CLAUDE.md and AGENTS.md if present.

If only one file exists, update it and create the missing counterpart only when the user asks for dual-file policy.

Apply balanced policy rules

Convert absolute rules ("always plan", "always use subagents") into conditional gates:

Scope gate for simple vs complex work
Required verification gate before completion
Subagent usage only when parallel/context-heavy work benefits

Keep mandatory quality bars:

No completion claims without evidence
Test/build/lint or equivalent verification required
Lessons capture only for reusable correction patterns

Keep policy compact and actionable

Prefer short, imperative bullets.

Avoid duplicate long blocks across files; either mirror concise content or keep one canonical and one pointer.

Keep task-specific procedures in task docs (tasks/todo.md) instead of expanding global policy files.

Validate before finishing

Confirm both files are consistent with the same workflow semantics.

Confirm no TODO placeholders remain.

Review diffs for overreach (policy-only change; no unrelated edits).

Required Policy Sections

When creating or normalizing policy docs, include these sections (exact names may vary):

Scope gate

Explore -> plan -> implement

Verification gate

Subagent strategy

Feedback/lessons loop

Context hygiene

Safety defaults

Output Contract

In the final response:

State which files changed.

Summarize policy behavior changes in 4-8 bullets.

Highlight any deliberately deferred item (for example, missing tasks/ directory).

improve-claude-agents