Add workspace skills suite to accelerate common development workflows

[rocketstack-matt]

Feature Proposal

Target Project:

Monorepo root (.github/skills/) — workspace-level AI customization

Description of Feature:

Introduce a suite of Copilot skills to guide users through common development workflows in the FINOS Architecture as Code project. Skills provide structured guidance, templates, and best-practice checklists for tasks like creating issues, writing Conventional Commits, planning tests, and authoring architecture documentation.

This accelerates onboarding, reduces mental load, ensures consistency with project standards (Conventional Commits, testing thresholds, schema validation), and makes high-quality contributions the path of least resistance.

User Stories:

• As a new contributor, I want guided workflows for common tasks so I don't have to hunt through docs or past PRs for format/conventions.
• As a maintainer, I want consistent, high-quality contributions so code review turnaround is faster and standards are enforced earlier.
• As a domain expert in CALM, I want specialized guidance for architecture validation and documentation so non-experts still produce valid, well-documented models.

Current Limitations:

• Project standards are documented (AGENTS.md, CONTRIBUTING.md, Governance.md) but require manual lookup and interpretation.
• Contributors often discover requirements during code review (commit message format, test coverage, changelog format) rather than during authoring.
• CALM-specific best practices (schema validation, relationship documentation) lack guided, interactive help.

Proposed Implementation:

Deploy 6 new skills in .github/skills/<skill-name>/SKILL.md, joining the existing draft-github-issue skill:

1. draft-github-issue (existing)

   • Guides creation of bugs, features, proposals, maintainer updates, etc. using templates from .github/ISSUE_TEMPLATE/
   • Status: ✅ Complete and deployed

2. conventional-commit-helper (new)

   • Helps users write Conventional Commits: <type>(<scope>): <subject>
   • References project-specific types, scopes (cli, calm-hub, shared, vscode, etc.), and best practices
   • Enforces commitlint rules interactively before commit
   • Relevant because: Project uses strict commitlint + husky hooks

3. test-plan-writer (new)

   • Structures unit and integration test plans with clear coverage targets
   • Reminds of >80% new-code coverage requirements
   • References repo test commands and package-specific testing guidance
   • Relevant because: All PRs require comprehensive tests; standards vary by package (npm workspaces vs. Java)

4. architecture-documentation (new)

   • CALM-specific: help document architectures, nodes, relationships, flows, controls, metadata
   • Validates against CALM schema constraints (1.2 release)
   • Provides examples of well-documented patterns
   • Relevant because: Core to project mission; docs are intricate and validation-heavy

5. pull-request-scaffolder (new)

   • Guides PR structure: title, description, testing approach, documentation impact, checklist
   • Links to relevant AGENTS.md/package-specific guidance
   • Ensures reviewability and standards compliance upfront
   • Relevant because: Complex monorepo with Java/TS, multiple platforms

6. changelog-entry-generator (new)

   • Helps write semantic-versioning-aligned changelog entries
   • Ties back to Conventional Commits to reduce duplication
   • Relevant because: Project maintains CHANGELOGs per package

7. calm-schema-validator-guide (new, optional)

   • CALM-specific: references schema rules, validates model structure, flags common mistakes
   • Provides diagnostic output and corrective guidance
   • Relevant because: Schema compliance is non-negotiable; errors caught early save review time

Technical Implementation:

• Each skill placed in .github/skills/<skill-name>/SKILL.md
• Include bundled assets (templates, reference docs) in each skill folder as needed
• Follow agent-customization SKILL format (YAML frontmatter, description, workflow, output rules)
• Skills reference package-specific AGENTS.md files (cli/, calm-hub/, calm-plugins/vscode/, etc.)

Alternatives Considered:

• Workspace instructions in copilot-instructions.md or AGENTS.md
  • Rejected: too broad; dilutes focus and overloads root-level context
• Extension-provided tools (e.g., GitHub PR extension)
  • Rejected: loses project-specific guidance on standards, conventions, CALM schema
• No additional guidance
  • Rejected: contributors discover requirements during review; slows iteration

Testing Strategy:

• Smoke tests for each skill:
  • draft-github-issue: Verify templates are correctly populated with test data
  • conventional-commit-helper: Test commit message validation against commitlint rules
  • test-plan-writer: Verify coverage targets and package-specific guidance are present
  • architecture-documentation: Validate CALM example output against schema
  • pull-request-scaffolder: Verify PR template includes all required sections
  • changelog-entry-generator: Verify entries align with Conventional Commits
  • calm-schema-validator-guide: Verify diagnostic output for invalid models
• Manual testing: Users invoke each skill and verify guidance is contextually relevant

Documentation Requirements:

• Update main README.md with "Copilot Skills" section describing available skills and how to invoke them
• Add section to CONTRIBUTING.md listing skills that support common workflows
• Each skill's SKILL.md includes clear trigger phrases so agent discovery works
• Short tutorial or video demonstrating a skill in action (optional, but high impact)

Implementation Checklist:

• Design reviewed and approved
• draft-github-issue skill finalized and tested (in progress)
• conventional-commit-helper skill created and validated
• test-plan-writer skill created and validated
• architecture-documentation skill created and validated
• pull-request-scaffolder skill created and validated
• changelog-entry-generator skill created and validated
• calm-schema-validator-guide skill created (optional) and validated
• All skills added to .github/skills/ directory structure
• README.md and CONTRIBUTING.md updated
• Tests written and passing
• Documentation complete
• Skills discoverable and working in Copilot chat

Additional Context:

• Builds on successful draft-github-issue skill created to support issue calm-ai: stop forcing Copilot model default and preserve user-selected model #2235 workflow
• Aligns with project values: high quality, consistency, accessibility to new contributors, automation of repetitive decisions
• Skills are workspace-specific; they live in .github/ and are shared across all contributors cloning the repo
• Future opportunities: skills for Java/Spring Boot upgrade workflows, Kubernetes/deployment guidance, API design patterns specific to CALM Hub

[rocketstack-matt]

Implementation Progress

Related PR: #2238 - Implements the draft-github-issue skill (first of the proposed suite)

This PR delivers the foundation skill that:

• Guides structured GitHub issue creation using repository templates
• Demonstrates the pattern for workspace-scoped skills in .github/skills/
• Can be used as a template for implementing the remaining skills

Next skills in the suite to implement:

• conventional-commit-helper
• test-plan-writer
• pull-request-scaffolder
• architecture-documentation
• changelog-entry-generator
• calm-schema-validator-guide (optional)