claude-plugin CLAUDE.md

team-management CLAUDE.md

Purpose

Complete team-management framework that enforces Discussion-Alignment-Implementation-Check (DAIC) methodology for AI pair programming workflows.

Narrative Summary

The team-management package transforms Claude Code from a basic AI coding assistant into a sophisticated workflow management system. It enforces structured collaboration patterns where Claude must discuss approaches before implementing code, maintains persistent task context across sessions, and provides specialized agents for complex operations.

The core innovation is the DAIC (Discussion-Alignment-Implementation-Check) enforcement through Python hooks that cannot be bypassed. DAIC mode is driven by the JSON protocol engine, which sets discussion, implementation, or documentation mode automatically per workflow step; it can also be switched manually via the daic_mode_switch_* MCP tools. In discussion mode the hooks block edit tools and require alignment before implementation proceeds. This prevents the common AI coding problem of immediate over-implementation without alignment.

The framework includes persistent task management with git branch enforcement, context preservation through session restarts, specialized subagents for heavy operations, and automatic context compaction when approaching token limits.

Key Files

Plugin Runtime & Configuration (the pip/npm installer was retired in #7)

• plugin/.claude-plugin/plugin.json - Plugin manifest wiring hooks / MCP server / commands / agents (version in sync with marketplace.json); no longer declares userConfig — provider tokens moved to a per-project, user-authored .claude/state/provider-tokens.json (the OS-keychain model was retired because the keychain is global-per-plugin-per-user, so two projects could not use different tokens). Marketplace descriptor: .claude-plugin/marketplace.json → ./plugin
• plugin/hooks/shared_state.py - Three-root path model (get_project_root() / get_plugin_root() / get_plugin_data()), shared state helpers, the file → config.json resolve_provider_token (reads the per-project .claude/state/provider-tokens.json; config.json is a legacy fallback), and ensure_provider_tokens_file (create-if-absent 0600 seeder for that file)
• plugin/hooks/_shim.py - Stdlib launcher shim every hook runs through (python3 ${CLAUDE_PLUGIN_ROOT}/hooks/_shim.py <hook>); selects the venv python if built, else system python
• plugin/hooks/hooks.json - Hook event → shim-command registrations (merge-friendly; the host merges them with the project's .claude/settings.json)
• plugin/mcp/bootstrap_mcp.py - MCP cold-start: builds/validates a venv under ${CLAUDE_PLUGIN_DATA} keyed to the requirements.lock hash, then os.execvs the venv python running server.py
• plugin/hooks/boot_detector.py - Guards against a legacy pip install coexisting with the plugin (SessionStart advisory + PreToolUse hard block)
• plugin/hooks/hook_utils.py - Shared hook helpers incl. module-level normalize_command() (hook-command canonicalisation; consumed by boot_detector.py)
• plugin/commands/config.md / plugin/commands/init.md - In-Claude-Code configuration slash commands that replaced the old install.py prompt flow
• plugin/mcp/tools/config.py - config_get / config_update MCP tools backing the config flow. config_get also returns a schema catalog ({key, type, allowed?, description} per settable key, on all return paths) so the flow knows each key's exact type/enum; the _CONFIG_SCHEMA allowlist covers the full non-secret settable surface incl. code_review.enforce_warnings, notifications.*, features.icon_style (m-fix-config-schema-exposure)
• plugin/hooks/config_intent_gate.py - Deterministic intent-gate hook routing config edits through the sanctioned flow
• plugin/agents/codex-cli.md - Wrapper agent that runs codex review --uncommitted / codex exec -s read-only in a sandboxed Task
• plugin/agents/agy-cli.md - Wrapper agent that runs agy --add-dir "$PWD" --dangerously-skip-permissions --print-timeout 300s -p ... (NO --sandbox) in a Task, contained by a project-local .agents/hooks.json read-only deny-gate
• plugin/templates/agy-readonly-gate.py - Stdlib PreToolUse deny-gate deployed into a project's .agents/hooks.json (named hook team-management-readonly-gate); hard-denys every agy tool call outside a read-only allowlist. Deployed by shared_state.ensure_agy_readonly_gate_deployed (merge-aware, refresh-on-change) when agy is enabled; the deploy also blanket-gitignores .agents/ in the host project (ensure_agents_dir_gitignored, mirroring .claude/)