governance-setup

name	governance-setup
description	Sets up Agent Teams governance (team-lead + architecture/qa/design leads) for large projects, or a Mini-PRD for small ones. Use this skill at project kickoff, whenever a team structure is needed, or on requests like "set up governance", "configure project team", or "create agent team" — do not skip it.
version	1.4.0
updated	"2026-03-03T00:00:00.000Z"

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

# 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

# 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:

# 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):

   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:

{
  "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):

# 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)