Initializing Governance

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