janekbaraniewski/openusage/dev-workflow-improvements

Skill: Dev Workflow Improvements

Audit and improve the OpenUsage development workflow. Ensures the dev flow is complete, consistent, and propagated to all AI tools.

When to use

• After adding/modifying a skill in docs/skills/
• After changing tool config content (code style, architecture, commands)
• When onboarding a new AI tool
• Periodically to check for drift or staleness
• When the development flow feels broken or incomplete

Architecture

Source of truth

docs/skills/tool-configs/template.md      ← shared content (style, architecture, commands)
docs/skills/tool-configs/skills-table.md   ← skills registry (single table, all skills)
docs/skills/<skill-name>/SKILL.md          ← individual skill specifications

Generated files (never edit directly)

.continuerules                    ← Continue.dev
.windsurfrules                    ← Windsurf
.github/copilot-instructions.md  ← GitHub Copilot
.aider/conventions.md            ← Aider
.opencode/skills/*/SKILL.md      ← OpenCode (thin stubs → docs/skills/)
.codex/skills/*/SKILL.md         ← Codex (thin stubs → docs/skills/)
.claude/commands/*.md             ← Claude Code (slash command stubs)

Generator

scripts/sync-tool-configs.sh — reads template + skills table, writes all generated files. Run via make sync-tools.

Phases

Phase 0 — Audit

1. Run make sync-tools and check if any files changed (git diff).

• If changes: report which files drifted and what changed.
• If clean: report "All tool configs are in sync."

1. Validate skill completeness:

• For each directory in docs/skills/*/:
• Has a SKILL.md?
• Listed in docs/skills/tool-configs/skills-table.md?
• Has a matching .claude/commands/<name>.md?
• Has a matching .opencode/skills/<name>/SKILL.md?
• Has a matching .codex/skills/<name>/SKILL.md?
• For docs/skills/add-new-provider.md:
• Listed in docs/skills/tool-configs/skills-table.md?
• Has .claude/commands/add-new-provider.md?
• Has .opencode/skills/add-new-provider/SKILL.md?
• Has .codex/skills/add-new-provider/SKILL.md?
• Report any gaps.

1. Validate skill references:

• For each skill's SKILL.md, check that referenced files exist:
• references/*.md files mentioned in the skill
• Source files mentioned (e.g., internal/core/types.go)
• Other skills referenced (e.g., /design-feature)
• Report broken references.

1. Check CLAUDE.md skills table matches skills-table.md:

• Compare the skills table in CLAUDE.md with docs/skills/tool-configs/skills-table.md.
• Report any mismatches.

Phase 1 — Fix

Based on audit findings, fix issues in priority order:

1. Sync drift: Run make sync-tools to regenerate.
2. Missing registrations: Add skill to skills-table.md, re-run sync.
3. Missing stubs: The sync script generates these automatically.
4. Broken references: Fix or remove stale file references in SKILL.md.
5. CLAUDE.md mismatch: Update the skills table in CLAUDE.md.

After each fix category, re-run the audit for that category to confirm.

Phase 2 — Improve

If the user requested workflow improvements (not just sync):

1. Quiz (ask the user):

• What part of the workflow feels broken or incomplete?
• Any new skills needed?
• Any existing skills that need updating?
• Any new AI tools to onboard?

1. Execute improvements based on answers:

• New skill: create docs/skills/<name>/SKILL.md, add to skills-table, run sync.
• Update skill: edit the SKILL.md, check if tool configs need template changes, run sync.
• New tool: add to scripts/sync-tool-configs.sh, add generation target, run sync.
• Workflow gap: identify the gap, propose a fix, implement after user approval.

1. Final sync: Run make sync-tools to propagate all changes.

Phase 3 — Verify

1. Run make sync-tools — should produce no changes (idempotent).
2. Run make build — project still compiles.
3. Run make test — tests still pass.
4. git diff — show all changes for user review.

Rules

1. NEVER edit generated files directly — always edit the source of truth and run sync.
2. Every new skill MUST be added to skills-table.md — this is the single registry.
3. After ANY skill change, run make sync-tools before committing.
4. The template is authoritative — if a tool config disagrees, the template wins.
5. Claude commands get more detail than other tools (phase breakdowns) — this is intentional.
6. OpenCode skills are thin stubs pointing to docs/skills/ — don't duplicate content.
7. Codex skills are thin stubs pointing to docs/skills/ — don't duplicate content.

Adding a new AI tool

1. Add a generate_config call in scripts/sync-tool-configs.sh.
2. Add the output file to the "Generated files" list in this doc.
3. Add the output file to docs/skills/tool-configs/README.md.
4. Run make sync-tools.
5. Commit the script change + generated file together.

Checklist

• [ ] make sync-tools produces no diff (all configs in sync)
• [ ] Every docs/skills/*/SKILL.md is in skills-table.md
• [ ] Every skill has a .claude/commands/<name>.md stub
• [ ] Every skill has a .opencode/skills/<name>/SKILL.md stub
• [ ] Every skill has a .codex/skills/<name>/SKILL.md stub
• [ ] CLAUDE.md skills table matches skills-table.md
• [ ] No broken file references in any SKILL.md
• [ ] make build passes
• [ ] make test passes