Align skill and agent frontmatter with Anthropic's current spec

[b-coman]

Context

Investigation into Anthropic's current skill/agent format specifications revealed several alignment gaps in ido4dev's skill and agent frontmatter. Since the OBS-09 audit (#2) already edits these files, fixing frontmatter is low marginal cost and ensures we're fully aligned with the Anthropic ecosystem.

Gaps found

1. Agent `tools` field uses invalid `mcp` value

Current state:
```yaml

agents/code-analyzer.md

tools: Read, Write, Glob, Grep, mcp

agents/technical-spec-writer.md

tools: Read, Write, Glob, Grep

agents/spec-reviewer.md

tools: Read, Glob, Grep
```

Problem: `mcp` is not a valid tool name. Valid tool names are specific tools (`Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`, `Agent`) or explicit MCP tool names (`mcp__server__tool`). Agents inherit all tools by default — if the field is omitted, the agent gets everything.

Fix: Either remove the `tools` field entirely (agents inherit all tools), or replace `mcp` with explicit MCP tool patterns like `mcp__plugin_ido4dev_ido4__*`.

2. Pipeline skills missing `disable-model-invocation: true`

Current state: `decompose`, `decompose-tasks`, `decompose-validate` don't have this field.

Problem: These are pipeline phases with side effects (file creation, MCP tool calls). Without `disable-model-invocation: true`, Claude may auto-load these skills during unrelated work if the user's prompt contains relevant keywords.

Fix: Add `disable-model-invocation: true` to all three decompose skills.

3. No `maxTurns` on agent definitions

Current state: None of our agents specify `maxTurns`.

Problem: Without this safety guardrail, a runaway agent continues indefinitely.

Fix: Add `maxTurns` to each agent. Suggested values:

• `code-analyzer`: 50 (extensive codebase exploration expected)
• `technical-spec-writer`: 30 (synthesis from canvas, less exploration)
• `spec-reviewer`: 15 (review protocol, bounded scope)

4. No `effort` field on agents

Current state: No agents specify `effort`.

Problem: Opus 4.6 supports `effort: max` for deep reasoning. Our agents (especially code-analyzer and technical-spec-writer) produce complex multi-section artifacts that benefit from maximum reasoning effort.

Fix: Add `effort: max` to code-analyzer and technical-spec-writer. Consider `effort: high` for spec-reviewer.

5. Plugin agents ignore `hooks`, `mcpServers`, and `permissionMode`

Current state: Not an issue today (we don't set these fields on plugin agents).

Note for future work: If we ever want scoped hooks or MCP servers on agents, they won't work from within a plugin. This is a platform restriction. Document in CLAUDE.md as a known constraint.

6. `memory` field (future consideration, not Round 4)

Available: Agents can specify `memory: project` to accumulate knowledge across sessions.

Potential value: `code-analyzer` could learn codebase patterns over time instead of re-discovering them each session.

Status: Not tested. Flag as Round 5+ investigation.

Deliverables

• Fix `tools` field in all 3 agent .md files
• Add `disable-model-invocation: true` to 3 decompose skills
• Add `maxTurns` to all 3 agent definitions
• Add `effort` to agent definitions where appropriate
• Document plugin agent restrictions in CLAUDE.md (brief note)

Acceptance criteria

• `claude plugin validate .` passes with zero warnings
• All frontmatter fields match Anthropic's current documented spec
• No behavioral regression (skills still trigger correctly, agents still spawn correctly)

Dependencies

• Independent (can be done in parallel with other Round 4 work)
• Natural to combine with OBS-09: Rule audit across agents and decompose skills #2 (OBS-09 audit) since we're editing the same files

References

• Claude Code Skills documentation
• Claude Code Sub-agents documentation
• Agent Skills specification
• Claude Code Plugins Reference
• `agents/code-analyzer.md` — current frontmatter (lines 1-9)
• `agents/technical-spec-writer.md` — current frontmatter (lines 1-10)
• `agents/spec-reviewer.md` — current frontmatter (lines 1-9)
• `skills/decompose/SKILL.md` — current frontmatter
• `skills/decompose-tasks/SKILL.md` — current frontmatter
• `skills/decompose-validate/SKILL.md` — current frontmatter