gandalf-skills

Reusable AI Skills for developing Gandalf, a minimal C Wayland compositor built on neu-swc.

Gandalf's project motto is:

One compositor to rule your desktop.

This repository is the long-term AI knowledge base for Gandalf. Its purpose is to capture durable project judgment: architecture rules, Wayland protocols, C ownership and neu-swc integration, debugging playbooks, release discipline, documentation standards, and code review expectations.

The implemented catalog covers planning, implementation, integration, debugging, review, packaging, testing, documentation, and releases.

Design Goals

• Keep the Skill catalog small, high-value, and composable.
• Prefer broad workflows over dozens of tiny task Skills.
• Teach project judgment, not only generate code.
• Preserve Gandalf's priorities: minimalism, modularity, readability, explicit C ownership, Unix-style tooling, hot-reloadable configuration, stable architecture, and strong documentation.
• Make every public Skill useful outside one narrow issue.
• Keep internal Skills for project governance, inspiration synthesis, and release policy where they encode Gandalf-specific decisions.

Repository Layout

gandalf-skills/
|-- README.md
|-- CONTRIBUTING.md
|-- LICENSE
|-- prompt.md
|-- docs/
|   |-- architecture/
|   |   `-- repository-design.md
|   |-- graphs/
|   |   `-- skill-dependencies.md
|   `-- roadmap/
|       `-- skill-roadmap.md
|-- shared/
|   |-- references/
|   |   `-- README.md
|   `-- templates/
|       `-- README.md
`-- skills/
    |-- planning/
    |-- architecture/
    |-- wayland/
    |-- c/
    |-- rendering/
    |-- configuration/
    |-- performance/
    |-- debugging/
    |-- documentation/
    |-- releases/
    |-- inspiration/
    |-- input/
    |-- ipc/
    |-- testing/
    |-- packaging/
    |-- security/
    |-- integration/
    |-- routing/
    `-- code-review/

Skill Catalog

The canonical Skill catalog is documented in docs/architecture/repository-design.md.

Implemented Skills:

• gandalf-project-planning
• gandalf-architecture-review
• gandalf-documentation
• gandalf-code-review
• c-compositor-development
• neuswc-integration
• wayland-protocol-workflow
• gandalf-debugging
• gandalf-configuration-design
• rendering-pipeline-work
• performance-investigation
• release-readiness
• inspiration-analysis
• input-seat-workflow
• ipc-and-command-interface
• test-harness-design
• packaging-and-nixos
• security-surface-review
• external-tool-integration
• feature-module-system
• gandalf-skill-router

Installation

Install all Skills from a local checkout:

npx skills add . --skill '*' -a codex

List discoverable Skills without installing:

npx skills add . --list

This repository currently lists twenty-one Skills with that command.

Install one Skill from a local checkout:

npx skills add . --skill gandalf-project-planning -a codex

To install Skills from Forgejo, use the archive URL. The Skills CLI does not currently recognize a Forgejo repository page as a well-known source, but it can install from Forgejo's generated archive:

npx skills add https://forgejo.ftmahringer.com/FTMahringer/gandalf-skills/archive/main.tar.gz --skill '*' -a codex
npx skills add https://forgejo.ftmahringer.com/FTMahringer/gandalf-skills/archive/main.tar.gz --skill gandalf-code-review -a codex

The top 10 highest-value Skills are:

1. gandalf-architecture-review
2. c-compositor-development
3. neuswc-integration
4. wayland-protocol-workflow
5. gandalf-debugging
6. gandalf-configuration-design
7. feature-module-system
8. external-tool-integration
9. rendering-pipeline-work
10. gandalf-skill-router

The former zig-compositor-development Skill was replaced by c-compositor-development. Reinstall the catalog after upgrading an existing installation so the renamed Skill and neuswc-integration are available.

Roadmap

Implementation order, release phases, and quality gates are documented in docs/roadmap/skill-roadmap.md.

Dependency Graph

The Skill dependency graph is documented in docs/graphs/skill-dependencies.md.

Non-Goals

• No additional Skill implementations until each Skill has an accepted spec.
• No large archive of copied external project docs.
• No feature-expansion Skills that push Gandalf away from minimal compositor design.