--- name: Dev Workflow Improvements slug: dev-workflow-improvements-2 category: DevOps description: Dev Workflow Improvements audits and fixes the OpenUsage development workflow, including tool config sync, skill registrations, and generated stubs. Use it after skill or config changes, or when the workflow feels incomplete or out of date. github: "https://github.com/janekbaraniewski/openusage/tree/main/docs/skills/dev-workflow-improvements" language: Go stars: 187 forks: 16 install: "npx degit https://github.com/janekbaraniewski/openusage/tree/main/docs/skills/dev-workflow-improvements ~/.claude/skills/dev-workflow-improvements" installs_to: ~/.claude/skills/dev-workflow-improvements source_path: docs/skills/dev-workflow-improvements/SKILL.md collection_size: 14 category_size: 1013 collection_url: "https://dirskills.com/collections/janekbaraniewski/openusage" added: 2026-09-06T05:20:24.005Z last_synced: 2026-09-06T05:20:24.005Z canonical_url: "https://dirskills.com/skills/dev-workflow-improvements-2" --- # Dev Workflow Improvements Dev Workflow Improvements audits and fixes the OpenUsage development workflow, including tool config sync, skill registrations, and generated stubs. Use it after skill or config changes, or when the workflow feels incomplete or out of date. **Install:** ```bash npx degit https://github.com/janekbaraniewski/openusage/tree/main/docs/skills/dev-workflow-improvements ~/.claude/skills/dev-workflow-improvements ``` ## README # 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.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." 2. 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/.md`? - Has a matching `.opencode/skills//SKILL.md`? - Has a matching `.codex/skills//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. 3. 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. 4. 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? 2. **Execute improvements** based on answers: - New skill: create `docs/skills//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. 3. **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/.md` stub - [ ] Every skill has a `.opencode/skills//SKILL.md` stub - [ ] Every skill has a `.codex/skills//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