governance-setup

> **v1.4.0**: **Mini-PRD support** (Progressive Disclosure + `/audit` compatible), removed `/project-bootstrap` dependency, added **local project team initialization (standalone)** path after governance completion # Governance Setup (Phase 0) > **Purpose**: Before implementation begins on a large project, the governance team establishes standards and quality baselines. > > **Standalone Goal (important)**: This project provides **implementation-assist skills + an Agent Team (Project Team)** and is designed to **operate fully standalone without external dependencies**. > > **Core Principle**: This skill **does not write implementation code**. It produces only **governance documents and standards**. > > **Prerequisites**: Having a TASKS.md is ideal. If absent, either (1) after governance completes, run **TASKS scaffolding** in the **local project team initialization (standalone)** step, or (optionally) generate TASKS with an external tool/skill. > > **v1.2.1**: Cleaned up frontmatter `trigger`, strengthened `/audit` integration, detailed Phase execution templates (standalone path reinforced in v1.3.0) --- ## Absolute Prohibitions 1. **No implementation code** — only standards and policy documents 2. **Do not skip agent order** — PM → Architect → Designer → QA → DBA sequence is mandatory 3. **Do not proceed without user confirmation** — user approval is required after each agent completes --- ## Immediate Actions on Trigger ### (Important) Document → Execution Link - This skill does not write implementation code, but for its outputs to carry real effect, **documents must be translated into enforceable mechanisms (gates/tests/types/CI)**. - Therefore `management/quality-gates.md` and `ADR-*.md` must include **"where and how it is enforced"** (e.g., a single verification entry command, CI job, test suite, artifact path). - Example: define a **single entry verification command** like `scripts/verify_all.sh` or `make verify`, and map each quality gate item as a sub-step under that command. ### Step 0: Prerequisite Check ```bash # The TASKS file may be at root (TASKS.md) or at docs/planning/06-tasks.md depending on the project. ls docs/planning/06-tasks.md 2>/dev/null || ls TASKS.md 2>/dev/null ls management/project-plan.md management/decisions/ADR-*.md 2>/dev/null ls management/mini-prd.md 2>/dev/null ``` **If TASKS.md is absent**: - Only a legacy file (`docs/planning/06-tasks.md`) exists → guide `/tasks-migrate` first (consolidate into TASKS.md) - No task file at all → continue governance, then guide `/tasks-init` as the next step after completion **If TASKS.md exists**: check the task count. - 30 or more tasks → after governance, recommend `/team-orchestrate` for parallel execution **Mini-PRD vs Full Governance selection**: - Small project (1–5 people) → **Mini-PRD** (`references/mini-prd/`) - Large project (6+ people) → **Full Governance** (5-phase agent team) --- ## Mini-PRD (Lightweight Alternative) > **Fast start**: For small projects that do not need a full governance team **File**: `management/mini-prd.md` ### Creating a Mini-PRD ```bash # Template reference references/mini-prd/mini-prd-template.md # Progressive Disclosure question set references/mini-prd/progressive-disclosure.md # /audit compatibility mapping references/mini-prd/audit-mapping.md ``` ### Phase-by-Phase Questions | Phase | Timing | Questions | |-------|--------|-----------| | **Phase 1** | Initial | purpose, features, tech-stack | | **Phase 2** | After skeleton complete | business-logic, data-model, api-contract | | **Phase 3** | During muscles phase | error-handling, edge-cases, performance | ### /audit Compatibility A Mini-PRD passes `/audit`'s planning-conformance check: ```bash # Mini-PRD alone is sufficient to pass management/mini-prd.md # Phase 1+2 required # When /audit runs /audit → ✅ Mini-PRD detected → ✅ Planning conformance verified → ✅ Architecture verified → ✅ DDD verified (data-model) ``` --- ## Governance Team — 5-Phase Sequential Execution | Step | Agent | Artifact | Detailed Guide | |------|-------|----------|----------------| | 1 | **PM** | `management/project-plan.md` | `references/phase-1-pm.md` | | 2 | **Architect** | `management/decisions/ADR-*.md` | `references/phase-2-architect.md` | | 3 | **Designer** | `design/system/*.md` | `references/phase-3-designer.md` | | 4 | **QA Manager** | `management/quality-gates.md` | `references/phase-4-qa.md` | | 5 | **DBA** | `database/standards.md` | `references/phase-5-dba.md` | ### On Entering Each Phase 1. Read the corresponding `references/phase-N-*.md` file 2. Invoke a Task using the template below (example): ```js Task({ subagent_type: "orchestrator", // follow the guidance in the phase file description: "PM: Draft project plan", prompt: "Follow instructions in `references/phase-1-pm.md` and write `management/project-plan.md`. Ask the user for any required input." }) ``` 3. Confirm completion conditions before moving to the next phase > Note: The `subagent_type` per phase takes its value from what is defined in `references/phase-N-*.md`. --- ## Governance Completion Checklist ``` management/ ├── project-plan.md ← PM ├── quality-gates.md ← QA Manager └── decisions/ ├── ADR-001-tech-stack.md ├── ADR-002-api-versioning.md ├── ADR-003-error-handling.md └── ADR-004-naming-convention.md design/system/ ├── tokens.md, components.md, layout.md, accessibility.md database/ └── standards.md ← DBA ``` --- ## Next Steps (CRITICAL) > **This section must be executed after the skill completes.** After governance completes, present next-step options via **AskUserQuestion**: ```json { "questions": [{ "question": "Governance setup complete! Choose your next step:", "header": "Next Steps", "options": [ {"label": "Local project team initialization (recommended)", "description": "(standalone) project-team install + .claude/project-team.yaml creation + domain agents + TASKS scaffolding"}, {"label": "Initial governance quality audit", "description": "/audit — comprehensive check of configured standards and quality gates"}, {"label": "Deficit analysis first", "description": "/eros — validate hidden assumptions and gaps (v1.10.0)"}, {"label": "Start implementing directly", "description": "/agile auto — Claude writes code directly (small projects only)"} ], "multiSelect": false }] } ``` > **Conditional guidance (auto-inserted)**: > - If TASKS.md was absent → prepend "TASKS.md is missing. Run `/tasks-init` first in the next step." to the top of the options. > - If TASKS.md has 30 or more tasks → prepend "You have 30+ tasks. `/team-orchestrate` is recommended for parallel execution." to the top of the options. ### Auto-execution by Selection | Selection | Action | |-----------|--------| | "Local project team initialization" | Execute **Standalone Init** section below | | "Initial governance quality audit" | `Skill({ skill: "quality-auditor" })` | | "Deficit analysis first" | `Skill({ skill: "eros" })` | | "Start implementing directly" | `Skill({ skill: "agile" })` | ### Standalone Init (Local Project Team Setup) When the user selects "Local project team initialization", run the following **in the current project directory** (never globally): ```bash # Install workers + hooks + Agent Teams env to the current project's .claude/ # The --local flag ensures project-scoped installation bash "${CLAUDE_PLUGIN_ROOT}/project-team/install.sh" --local --mode=team --force --quiet ``` This installs to `<project-root>/.claude/`: - Worker agents (Builder, Reviewer, Designer, MaintenanceAnalyst) - 19 governance hooks - `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env flag in settings.json - Agent Teams leads to `~/.claude/agents/` (global, since they are shared templates) **CRITICAL**: Always use `--local`. Never use `--global` from within a project — governance artifacts (hooks, workers) must be project-scoped so different projects can have different configurations. --- ## Hook Integration | Artifact | Hook | Behavior | |----------|------|----------| | ADR-*.md | `standards-validator` | Warns on ADR violations | | quality-gates.md | `quality-gate` | Blocks on quality shortfalls | | design/system/*.md | `design-validator` | Detects design violations | | database/standards.md | `standards-validator` | Checks DB naming conventions | --- ## FAQ **Q: I don't have a TASKS.md** → Run `/tasks-init` first (generates scaffolding) **Q: I want to re-run a specific phase only** → Read the corresponding `references/phase-N-*.md` then invoke the Task **Q: Agent invocation failed** → Check `ls .claude/agents/` in your project root (run `project-team/install.sh --local --mode=team` if missing) **Q: Planning documents are too long** → Run `/compress optimize docs/planning/*.md` (extracts key content with the H2O pattern) --- **Last Updated**: 2026-03-03 (v1.4.1 - Context Optimize integration)