refactor: unified spec, skills, and workflow organization#1488
Draft
refactor: unified spec, skills, and workflow organization#1488
Conversation
Move *.spec.md files from docs/internal/design/ into capability domain directories under specs/: sessions/, control-plane/, integrations/, agents/. Update all cross-references in devflow skill, guide files, and within the moved specs themselves. Historical metrics data in scripts/coderabbit-triage/ intentionally left unchanged. Part of #1478 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move conventions, patterns, and standards files into domain-organized directories under specs/standards/: - backend/ — conventions, error handling, K8s client patterns - frontend/ — conventions, React Query patterns - control-plane/ — operator conventions - security/ — security standards - platform/ — cross-cutting conventions (CodeRabbit-derived) Update all references in agent definitions, amber-review skill, CLAUDE.md, and BOOKMARKS.md. Part of #1478 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rename *.guide.md to *.workflow.md and move from docs/internal/design/
to workflows/{domain}/:
- sessions/ambient-model.workflow.md
- control-plane/control-plane.workflow.md
- integrations/mcp-server.workflow.md
Fix pre-existing broken reference to ambient-data-model.md. Update
cross-references in devflow skill, manifests README, and design README.
Part of #1478
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move .claude/skills/ to top-level skills/ directory with capability domain organization: - Cross-cutting skills flat at root: devflow, align, amber-review, scaffold, memory, pr-fixer - Domain-nested: sessions/, control-plane/, frontend/, integrations/ Create .claude/skills symlink → ../skills/ for Claude Code discovery. Update convention-guard.sh to match both paths. Fix pre-existing broken .claude/context/ references in devflow skill. Part of #1478 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Delete plan.md, tasks.md, research.md, quickstart.md, and checklists/ from numbered spec directories. These are stale development artifacts that don't belong alongside specs (desired state descriptions). Part of #1478 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add specs/, workflows/, skills/ to CLAUDE.md structure section. Update BOOKMARKS.md with new Specs, Workflows, and Standards sections replacing the old Component Development Guides and Cross-Cutting Conventions sections. Fix stale .claude/patterns/ and .claude/context/ references. Part of #1478 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move skills/ and workflows/ under .agents/ to follow the agentskills.io
convention:
- .agents/skills/ — domain-nested storage (sessions/, control-plane/,
frontend/, integrations/) with cross-cutting skills flat at root
- .agents/workflows/ — domain-nested agent procedures
- .claude/skills symlinks to .agents/skills/ for Claude Code discovery
(top-level only: cross-cutting skills)
- specs/{domain}/.agents/skills symlinks to .agents/skills/{domain}/
for domain-scoped skill discovery
Update all references across CLAUDE.md, BOOKMARKS.md, devflow skill,
convention guard, spec files, design docs, and workflow files.
Part of #1478
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add .claude/skills symlinks alongside .agents/skills in each spec
domain directory so Claude Code discovers domain-specific skills
when working within a domain context.
Chain: specs/{domain}/.claude/skills -> ../.agents/skills ->
../../../.agents/skills/{domain}
Part of #1478
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Mandatory first step for all coding and spec work. The skill walks
agents through identifying relevant capability domains, cd'ing into
specs/{domain}/ to discover domain-specific skills via .claude/skills
symlinks, loading relevant specs, and checking applicable standards.
Part of #1478
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Establishes the principles, format, and organization conventions for specs: desired state (not issue tracking), living documents (amended or deleted, never archived), behavior contracts with RFC 2119 keywords, and Given/When/Then scenarios. Part of #1478 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Guides agents through creating specs that follow the project's format and conventions. Requires reading specs/index.spec.md before proceeding, enforces behavior-contract focus over implementation details, and walks through domain identification, context discovery, and RFC 2119 usage. Part of #1478 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add brevity instruction to discover skill output. Clarify that implementation invariants (not plans) may appear in specs, and remove redundant "execution plans" bullet from the avoid list. Part of #1478 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add .agents/workflows/specs/spec-change.workflow.md defining the full 7-phase spec change process: frame, draft, critic pass, synthesize, design questions, apply fixes, second critic pass. Update spec skill to require reading both specs/index.spec.md and the workflow before proceeding, and restructure steps to follow the workflow phases. Part of #1478 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Insert a codebase grounding phase between framing and drafting. The agent reads existing specs and code in affected areas, summarizes its understanding back to the user in 3-5 sentences, and only asks questions where the codebase is genuinely ambiguous. Saves the user from answering things the agent can verify itself. Renumber subsequent phases (now 8 total). Update spec skill to match. Part of #1478 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for cheerful-kitten-f556a0 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Move canonical storage from .agents/ to top-level directories: - skills/ — canonical home for all agent skills - workflows/ — canonical home for all agent workflows - .agents/skills and .agents/workflows become symlinks (projection) - .claude/skills points directly to skills/ Update all references across CLAUDE.md, BOOKMARKS.md, skill files, spec files, workflow files, design docs, and convention guard. Part of #1478 Co-Authored-By: Claude Opus 4.6 (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
Implements #1478 — unified location, format, and conventions for specs, skills, and workflows.
Three top-level directories
specs/— desired state of the system, organized by capability domain (sessions, agents, control-plane, integrations) with cross-cutting standards underspecs/standards/skills/— Agent Skills (agentskills.io), domain-nested with cross-cutting skills flat at rootworkflows/— agent-consumable procedures, domain-nestedProjections (symlinks)
.claude/skills -> ../skills— Claude Code discovers top-level (cross-cutting) skills.agents/skills -> ../skills— agentskills.io standard projection.agents/workflows -> ../workflows— agentskills.io standard projectionspecs/{domain}/.agents/skills -> ../../../skills/{domain}— domain-specific skill storagespecs/{domain}/.claude/skills -> ../.agents/skills— Claude Code discovers domain skills in contextNew content
specs/index.spec.md— spec ethos, RFC 2119 format with Given/When/Then scenarios, organization conventions/discoverskill — mandatory first step for all coding/spec work; walks through domain discovery/specskill — guides spec creation following the project format and 8-phase spec-change workflowspec-change.workflow.md— 8-phase process: frame, ground in codebase, draft, critic pass, synthesize, design questions, apply fixes, second critic passWhat moved
docs/internal/design/*.spec.mdspecs/{domain}/docs/internal/design/*.guide.mdworkflows/{domain}/*.workflow.mdDEVELOPMENT.md,*_PATTERNS.mdspecs/standards/{domain}/docs/security-standards.mdspecs/standards/security/security.spec.mddocs/coderabbit-derived-conventions.mdspecs/standards/platform/cross-cutting.spec.md.claude/skills/*skills/(with domain nesting)Deleted
Test plan
.claude/skills/symlink resolves and Claude Code discovers top-level skillsspecs/{domain}/.claude/skillssymlinks resolve to domain-specific skills/discoverand/specskills to confirm they work end-to-endCloses #1478