initializing-governance

name	initializing-governance
description	Initializes complete governance framework including constitution, roadmap, and templates. Use when setting up new projects or establishing governance in existing projects lacking systematic documentation.

Initialize Governance Framework

Creates the three-tier governance hierarchy: 1. **Constitution** (`CONSTITUTION.md`) - Immutable design principles 2. **Roadmap** (`ROADMAP.md`) - Strategic + tactical plans 3. **Process Documentation** (README files) - Operational guidance

Phase 1: Discovery and Planning

1. Detect Project Structure

Use Bash to check current state:

# Check for git repository
git rev-parse --show-toplevel

# Check for existing wingman workspace
ls -la .wingman/ 2>/dev/null || echo "No .wingman directory"

# Check for existing governance docs
[ -f .wingman/config/CONSTITUTION.md ] && echo "Constitution exists" || echo "No defining-constitution"
[ -f .wingman/ROADMAP.md ] && echo "Roadmap exists" || echo "No roadmap"

2. Ask User for Project Context

Use AskUserQuestion to gather essential information:

AskUserQuestion({
  questions: [
    {
      question: "What is the core mission of this project in one sentence?",
      header: "Mission",
      options: [
        { label: "I'll type it myself", description: "Provide custom mission statement" }
      ],
      multiSelect: false
    },
    {
      question: "What stage is this project currently in?",
      header: "Stage",
      options: [
        { label: "Brand new", description: "Just starting, no code yet" },
        { label: "Early development", description: "Some code exists, still evolving" },
        { label: "Active development", description: "Established codebase, ongoing features" },
        { label: "Mature", description: "Stable codebase, maintenance mode" }
      ],
      multiSelect: false
    },
    {
      question: "Do you have existing design principles or guidelines?",
      header: "Principles",
      options: [
        { label: "Yes, documented", description: "Have written principles already" },
        { label: "Yes, informal", description: "Have ideas but not written down" },
        { label: "No, need help", description: "Want to create them now" }
      ],
      multiSelect: false
    }
  ]
})

3. Create Directory Structure

Ensure all required directories exist:

# Create directories if they don't exist
mkdir -p .wingman
mkdir -p .wingman/plans

# Note: .wingman/issues and .wingman/specifications are created by session hooks

4. Create Process Documentation

Create standard process documentation files from templates (sourced from .wingman/playbooks/templates/ or builtins):

# Copy TESTING.md from playbooks templates
cp .wingman/playbooks/templates/testing.md .wingman/TESTING.md

TESTING.md will be populated later by setting-up-git-hooks with actual test commands.

Initial state should have placeholder status:

• Replace {{STATUS_PLACEHOLDER}} with: **Status:** Not configured yet
• Leave {{TEST_COMMAND}} and other placeholders as-is
• These will be filled in by setting-up-git-hooks

Note on Templates: Templates are provisioned to .wingman/playbooks/templates/ during workspace initialization:

• Issue templates: .wingman/playbooks/templates/issues/ (bug.md, task.md, feature-request.md)
• Specification template: .wingman/playbooks/templates/specification.md
• Security checklist: .wingman/playbooks/templates/security-checklist.md
• Definition of Done: .wingman/playbooks/templates/definition-of-done.md

These are copied from agent-core builtins during init_workspace. User customizations in .wingman/playbooks/templates/ are preserved.

5. Set Up Git Hooks (Automatic)

After governance files are created, automatically set up git hooks:

# Invoke setting-up-git-hooks skill
Skill: setting-up-git-hooks

This will:

• Populate .wingman/TESTING.md (created in previous step)
• Detect project type and configure appropriate hooks
• Create .wingman/config/hooks-config.json with configuration
• Install hooks to .git/hooks/ directory
• Handle empty projects gracefully (creates placeholders)

Users can reconfigure later with /wingman:updating-git-hooks command.

Phase 2: Constitution Creation

If user has existing principles: Use the defining-constitution skill (invoke with Skill tool) to help them refine and formalize.

If user needs help creating principles: Guide them through brainstorming process:

1. Identify Core Values

Ask these questions (one at a time, discussion-style):

• "What matters most to you in this project's design and architecture?"
• "What are the non-negotiables - things you'd refuse to compromise on?"
• "What mistakes have you seen in similar projects that you want to avoid?"
• "What does success look like for this project in 2 years?"

2. Convert Values to Principles

For each core value, help user formulate as concrete principle:

Template:

### [Principle Number]: [Principle Name]

**Principle**: [One-sentence statement of the principle]

**In Practice**:
- [Specific application 1]
- [Specific application 2]
- [Specific application 3]

**Anti-patterns** (What NOT to do):
- [Anti-pattern 1 with explanation]
- [Anti-pattern 2 with explanation]

**Examples**:
- **Good**: [Concrete example showing principle in action]
- **Bad**: [Concrete example violating principle]

3. Write Constitution File

Use the constitution template from .wingman/playbooks/templates/ or builtins:

# Copy template (if not using the skill to generate it)
cp .wingman/playbooks/templates/constitution.md .wingman/config/CONSTITUTION.md

Then use Edit tool to fill in:

• Project name
• Current date for ratification
• North Star mission (from Phase 1)
• 5+ principles (from brainstorming)
• Decision framework (can use default)
• Amendment process (can use default)

Phase 3: Roadmap Creation

1. Gather Roadmap Information

Ask user about phases and goals:

AskUserQuestion({
  questions: [
    {
      question: "How many major phases do you envision for this project?",
      header: "Phases",
      options: [
        { label: "1-2 phases", description: "Small project, focused scope" },
        { label: "3-4 phases", description: "Medium project, several major milestones" },
        { label: "5+ phases", description: "Large project, long-term vision" }
      ],
      multiSelect: false
    }
  ]
})

2. For Each Phase, Gather Details

For first phase (most important):

• "What's the main goal of Phase 1?"
• "What features are essential for Phase 1?"
• "What does success look like at the end of Phase 1?"
• "What's the timeline for Phase 1?"

For subsequent phases (can be less detailed):

• "What's the main goal of Phase N?"
• "What key features belong in Phase N?"

3. Write Roadmap File

Use the roadmap template from .wingman/playbooks/templates/ or builtins:

# Copy template (if not using the skill to generate it)
cp .wingman/playbooks/templates/roadmap.md .wingman/ROADMAP.md

Fill in with Edit tool:

• Project name and overview
• Current state (what's already done)
• Each phase with timeline, goal, features, success metrics
• Link to defining-constitution principles

Phase 4: Process Documentation

1. Create Issues README

Create a minimal README with status metrics for the issues directory.

Use Edit tool to:

• Update "Status" section with current counts (run issues_list to get counts)
• Update "Metrics" section with actual data
• Keep rest of template as-is (it's generic guidance)

2. Create Specifications README

Create a minimal README with status metrics for the specifications directory.

Use Edit tool to:

• Update "Status" section with current counts
• Update "Current Phase" section from roadmap
• Update "Metrics" section with actual data
• Keep rest as guidance

Note: Templates are provisioned to .wingman/playbooks/templates/ during workspace initialization from agent-core builtins. User customizations in that directory are preserved.

Phase 5: Integration and Verification

1. Update Project CLAUDE.md

If CLAUDE.md exists in project root, add governance section:

## Project Governance

This project uses a three-tier governance framework:

### Tier 1: Constitution (Immutable Principles)
**File**: `.wingman/config/CONSTITUTION.md`

Supreme law of the project. All features and decisions must align with constitutional principles.

**Read this first** before working on any feature.

### Tier 2: Strategic Roadmap
**File**: `.wingman/ROADMAP.md`

Multi-phase strategic plan showing project direction and feature phasing.

### Governance Workflow

Before implementing any feature:
1. Check constitutional alignment
2. Verify roadmap phase
3. Create/update specification
4. Break into tracked issues
5. Follow TDD implementation

**Critical**: Use the `checking-constitutional-alignment` skill before starting new features.

2. Verify All Files Created

Run verification:

# List all governance files
echo "=== Governance Files ==="
ls -lh .wingman/config/CONSTITUTION.md
ls -lh .wingman/ROADMAP.md
ls -lh .wingman/specifications/README.md
ls -lh .wingman/issues/README.md

echo ""
echo "=== Directory Structure ==="
tree -L 2 .wingman/

3. Create Welcome Issue

Use issues_create to create first issue explaining governance:

issues_create({
  title: "Welcome to Project Governance Framework",
  description: `## Governance Framework Initialized

This project now has a complete governance framework to ensure alignment between AI assistant and human partner.

### Key Documents

**Constitution** (\`.wingman/config/CONSTITUTION.md\`)
- Immutable design principles
- Decision framework
- Amendment process

**Roadmap** (\`.wingman/ROADMAP.md\`)
- Strategic multi-phase plan
- Feature phasing
- Success metrics

### Quick Start

1. Read the Constitution first
2. Review the Roadmap to understand phases
3. Use MCP tools or skills to create issues/specs

### Next Actions

- [ ] Read CONSTITUTION.md thoroughly
- [ ] Review ROADMAP.md phases
- [ ] Identify first features to implementing-issue
- [ ] Create specifications for Phase 1 features
- [ ] Begin implementation following governance

### Skills Available

- \`checking-constitutional-alignment\` - Verify feature alignment
- \`defining-constitution\` - Refine principles and clarity
- \`verifying-governance\` - Check governance integrity
- \`refreshing-metrics\` - Update status metrics

Close this issue once you've reviewed all governance documents.
  `,
  type: "issue",
  status: "open",
  priority: "high",
  labels: ["governance", "onboarding"],
  project: "Governance Framework"
})

Phase 6: User Handoff

Provide Summary to User

Create summary message:

## Governance Framework Initialized

Your project now has a complete governance system ensuring we stay aligned on:
- Design principles (Constitution)
- Strategic direction (Roadmap)

### Files Created

**Core Governance** (in `.wingman/`):
- `CONSTITUTION.md` - [X] principles ratified
- `ROADMAP.md` - [Y] phases planned

**Process Documentation** (in `.wingman/`):
- `issues/README.md` - Issue management guide
- `specifications/README.md` - Specification guide
- `TESTING.md` - Test documentation (created here, populated by setting-up-git-hooks)

**Git Hooks** (always enabled):
- `.wingman/config/hooks-config.json` - Hook configuration
- `.git/hooks/pre-commit` - Pre-commit hook
- `.git/hooks/pre-push` - Pre-push hook

### Next Steps

1. **Review Constitution**: Read `.wingman/config/CONSTITUTION.md`
   - Verify principles match your vision
   - Use `defining-constitution` skill if refinement needed

2. **Review Roadmap**: Read `.wingman/ROADMAP.md`
   - Confirm phases and timelines
   - Adjust priorities if needed

3. **Start Implementation**:
   - Create specifications for Phase 1 features
   - Use `writing-plans` skill to break into tasks
   - Follow governance workflow for all features

<success_criteria>

• .wingman/config/CONSTITUTION.md created with core principles
• .wingman/ROADMAP.md created with project phases
• .wingman/issues/README.md and .wingman/specifications/README.md created
• Git hooks configured (if applicable)
• CLAUDE.md updated with governance references
• Welcome/orientation issue created for the project
• User handoff summary provided with next steps </success_criteria>

References

For detailed information, see:

• references/detailed-guide.md - Complete workflow details, examples, and troubleshooting