v0.3.0: slash commands in correct folder + orchestration skills + review-delta ADR#2
Merged
nachiket-p merged 6 commits intomainfrom Apr 23, 2026
Merged
v0.3.0: slash commands in correct folder + orchestration skills + review-delta ADR#2nachiket-p merged 6 commits intomainfrom
nachiket-p merged 6 commits intomainfrom
Conversation
…lags The shipped CLAUDE.md/AGENTS.md templates grew a verbose preamble and a stale "Not yet built" section listing commands (list/get/graph/next/search) that have since been implemented. More importantly, the command list showed only the minimal `docops new ctx "title"` form, so agents would create a stub file and then try to Write() content into it — failing the read-before-edit guardrail many runtimes enforce. Now the template shows `--body -|TEXT` / `--body-file PATH` inline and calls out "populate at creation" explicitly to avoid the stub-then-rewrite round-trip. The "Notes for humans" footer story is replaced with a one-line blockquote. The docops block stays byte-identical between the two templates (TestAgentsClaudeBlocksInSync passes). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Both were left as draft but their implementations shipped in v0.2.0: - ADR-0023 update-check — TP-021 done - ADR-0024 CLAUDE.md alongside AGENTS.md — TP-022 done Regenerated STATE.md and .index.json via docops refresh. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a cheap review-delta loop to DocOps so ADRs whose citing tasks have all shipped don't silently drift from the code that claims to implement them: - ADR-0026 (draft) proposes an optional `reviewed_at` ADR frontmatter field and a new `docops review` command. The command lists ADRs where implementation=done but reviewed_at is missing or predates the newest commit touching files referenced by citing tasks; with an ID it prints the ADR body + relevant commits so the agent can assess drift; `--mark` stamps today's date. STATE.md surfaces the stale-review count. - TP-029 tracks shipping that CLI + schema work. - TP-023 scope expanded with Phase 2: ship gstack-style orchestration skills (/docops:progress, /docops:do, /docops:plan, /docops:close, /docops:review). Priority bumped p2 → p1 since agents running against DocOps today need these to drive the workflow, not just the thin read-command wrappers Phase 1 covers. Rationale on why `reviewed_at` is source rather than computed: ADR-0010 already derives `implementation` state from citing tasks, but review itself is human+agent judgment — reading shipped code against the decision — so the sign-off can't be inferred from filesystem state. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The read-command skills went missing when the bundle was trimmed before v0.2.0 — the CLI exposed five commands without matching skills, so an agent that learned "/docops:next" under v0.1.x silently lost the affordance after upgrade. Restores all five with frontmatter and bodies matching the existing skill tone: terse, point at the CLI, no embedded domain knowledge that belongs in --help. Flag coverage in the lint test (flagAllowlist) mirrors the actual cmd_*.go flag sets. Two upgrader fixtures that used next.md as the "stale skill removed upstream" case are updated to old-command.md so they survive next.md re-entering the bundle. Phase 2 (orchestration skills) still to come; TP-023 stays active. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds four gstack/gsd-style orchestration skills — thin shells that sequence multiple docops commands and prompt the user through a workflow, modelled on the pattern /gsd-progress, /gsd-do, /gsd-ship use successfully: - /docops:progress — state + audit + next → single situational briefing. - /docops:do — NL intent router; maps freeform requests to the right /docops:* skill, never does the work itself. - /docops:plan — converts a CTX into an ADR plus citing tasks via `docops new ... --body -` heredocs (no stub-then-rewrite round-trip). Human-confirmed before every write. - /docops:close — finish-task loop: verify acceptance → flip status to done → refresh → stage commit → propose message. User approves before anything lands. /docops:review is deliberately deferred to TP-029 (the `docops review` command it would wrap doesn't exist yet) per TP-023's phase 2 scope. Closing TP-023 — phase 1 (read-command wrappers) shipped in afcd855; phase 2 is the commit above. The blocked /docops:review skill will land alongside its CLI under TP-029. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Claude Code reads slash commands from .claude/commands/<ns>/<cmd>.md and skills from .claude/skills/<name>/SKILL.md (one directory per skill, different frontmatter contract). DocOps was writing flat files under .claude/skills/docops/ which Claude Code registered as neither — the /docops:* namespace was effectively invisible in Claude Code sessions (Cursor worked because .cursor/commands/docops/ was the right shape). Retargets init and upgrade to write into .claude/commands/docops/ to match the Cursor layout and the /docops:* invocation pattern the skill bodies already assumed. Upgrade also removes every file sitting in the old .claude/skills/docops/ location so v0.2.x users don't end up with the same slash command mounted from two folders. Legacy cleanup is best-effort — os.RemoveAll semantics on missing paths, no failure when the folder never existed. Test coverage for the migration added as TestRun_MigratesLegacyClaudeSkillsFolder. Dogfooded via `docops upgrade --yes` on this repo: Claude Code's skills list now shows docops:refresh, docops:do, docops:search, docops:new-adr, docops:get, docops:next, docops:state, docops:progress, docops:init, docops:list, docops:close, docops:audit, docops:new-ctx, docops:new-task, docops:plan, docops:upgrade, docops:graph — all 17. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ships six commits that add DocOps orchestration skills, fix Claude Code slash-command discoverability, and promote two accepted ADRs.
/docops:*from.claude/commands/docops/, not.claude/skills/docops/. Retargets init + upgrade; legacy cleanup removes old-location files on upgrade. (380ee51)reviewed_atADR frontmatter anddocops reviewcommand to catch ADR/code drift once implementation flips to done.--body/--body-fileondocops newto avoid the stub-then-rewrite round-trip.Dogfooded via
docops upgrade --yeson this repo — all 17/docops:*slash commands now register with Claude Code; Cursor layout unchanged.Test plan
go test ./...green (59 docs validate clean, new migration testTestRun_MigratesLegacyClaudeSkillsFolderpasses)docops upgrade --dry-runagainst this repo produces expected migration plan (17 removes from legacy folder, 17 adds to new folder + 17 renames visible in git log)docops refreshclean: 0 errors, 0 warningsmake release VERSION=0.3.0to cut tag + trigger goreleaser (Homebrew tap + Scoop bucket)🤖 Generated with Claude Code