Project Advisor

Project Advisor

Governance layer for project management. Reads per-project configuration from workflow/projects/*.yaml to know field values, governance rules, and state mappings. Actual execution (creating issues, updating fields) goes through the github-projects-manager skill.

This skill is cross-cutting — applies to every repo that uses GitHub Projects or Azure DevOps Boards, not just The Bridge.

Project Registry

Configuration lives in workflow/projects/*.yaml. Each file defines one project:

• Field values (status, priority, type, size, stage, etc.)
• Governance rules (K/W/B levels, per-rule overrides)
• State mappings (project status → normalized state for trackers)
• Review comment templates

projects/
├── _schema.yaml              # Schema documentation
├── _template.yaml            # Blank template for new projects
├── examples/                 # Neutralized examples (CORE layer)
│   ├── operational.yaml      # Type A: management, coordination
│   ├── technical.yaml        # Type B: software development
│   ├── minimal.yaml          # Type C: workshops, experiments
│   └── ado-project.yaml      # Azure DevOps integration
└── {slug}.yaml               # Actual project configs (USER layer)

When creating issues or updating fields: always read the matching workflow/projects/{slug}.yaml first. Use the field values defined there — never hardcode emojis, status names, or priority values.

When This Skill Activates

• User asks about project setup or structure
• User wants to validate board health or check governance
• Crew-advisor detects untracked work that should be an issue
• After issue creation (verify governance rules were followed)

Decision Tree

User intent?
├─ "Set up a GitHub project"         → references/setup.md
├─ "Create issue" / "Track this"     → Issue Governance (below) + references/execution.md
├─ "Show board" / "What's active?"   → Board Overview (below)
├─ "Check board health"              → references/governance.md (R1-R7) + execution.md (jq queries)
├─ "Update issue status/fields"      → references/execution.md (CLI + GraphQL patterns)
├─ "Convert drafts to issues"        → references/execution.md (Draft-to-Issue section)
├─ "Add a new project"               → Create workflow/projects/{slug}.yaml from _template
└─ General project question           → Answer from governance.md + project config

Issue Governance (guided flow)

When creating an issue (execution patterns in references/execution.md):

1. Load project config

• Match context to workflow/projects/*.yaml (by project number or name)
• Read fields: for valid values, governance: for rules
• If no config exists: offer to create one from _template.yaml

1. Determine project type from config project.type:

• operational → has assignment + dependency fields
• technical → has stage + size fields
• custom → minimal fields, check what's available

1. Propose issue (use field values from config):

``` Issue proposal: Title: {derived from conversation} Repo: {from config project.issue_repo} Project: #{number} {name} Fields: (per config) Status: {config fields.status.default} Priority: {suggested from config values} Type: {suggested from config values}

[y] Create [e] Edit [n] Cancel ```

1. Create via github-projects-manager skill

1. Verify — confirm issue is on the board after creation

Board Overview

Query active items (exclude done_states from config), show grouped by status with assignee and priority.

Field Update Rules

Read governance.rules from project config. At minimum:

K-level (Critical — from config governance.level: strict|standard):

• done_requires_review: must go through reviewstates before donestates
• review_needs_comment: mandatory comment using review_comment_template
• done_only_by_user: only human can mark done
• never_delete: use Declined, never delete

W-level (Workflow):

• assignee_on_in_progress: must have assignee when in progress
• comment_on_status_change: comment on every transition

See references/governance.md for the full K/W/B rule set with board health validation checks (R1-R7).

Governance Levels

| Level | K rules | W rules | B rules | |-------|---------|---------|---------| | strict | Enforced | Enforced | Suggested | | standard | Enforced | Suggested | Optional | | relaxed | Enforced | Informational | Informational |

Integration with Bridge

• Trackers: state_map in project config feeds into tracker normalization
• Task Management: When creating a work task, offer to also create an issue
• Crew Advisor: When untracked work detected, suggest task + issue creation
• Promote: After promoting CORE changes, suggest linking to issues

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bks-lab
• Source: bks-lab/open-bridge
• License: MIT
• Homepage: https://bks-lab.github.io/open-bridge/

Install and usage instructions live in the source repository linked above.