proposal: unified spec location, format, and update workflow

[jsell-rh]

Background

Specs, standards, skills, and workflows were scattered across 5+ locations with inconsistent formats and no shared lifecycle convention. This issue tracks the consolidation into a unified structure.

Implemented Structure

Three organizational concepts, each with a clear home:

• Specs — desired state of the system
• Skills — portable agent capabilities (agentskills.io standard)
• Workflows — agent-consumable procedures for accomplishing work

Directory Layout

specs/                                    # Desired state of the system
  index.spec.md                           # Spec ethos, format, conventions
  {capability-domain}/                    # One dir per domain
    *.spec.md
    .agents/skills -> symlink             # Domain-specific skills
    .claude/skills -> symlink             # Claude Code discovery
  standards/                              # Cross-cutting engineering constraints
    {domain}/*.spec.md

.agents/                                  # Agent tooling
  skills/                                 # All skills, domain-nested
    {skill-name}/SKILL.md                 # Cross-cutting (flat at root)
    {domain}/{skill-name}/SKILL.md        # Domain-specific (nested)
  workflows/
    {domain}/*.workflow.md                # Agent procedures

.claude/skills -> ../.agents/skills       # Claude Code discovers top-level skills

Capability Domains

Domain	Covers
sessions/	Lifecycle, initialization, status, messages, events, data model
agents/	Agent model, runtime registry, prompts, runners
control-plane/	Reconciliation, operator, scheduling
integrations/	MCP, Gerrit, external services
standards/	Cross-cutting engineering constraints by component

Spec Format

Specs use RFC 2119 keywords (SHALL, MUST, SHOULD, MAY) with Given/When/Then scenarios. See specs/index.spec.md for the full format definition. Key principles:

1. Specs describe desired state, not issues or fixes
2. Specs are amended, replaced, or deleted — never archived
3. Specs are behavior contracts, not implementation plans
4. Specs are organized by capability domain

What Moved

From	To
docs/internal/design/*.spec.md	specs/{domain}/
docs/internal/design/*.guide.md	.agents/workflows/{domain}/*.workflow.md
Component DEVELOPMENT.md, *_PATTERNS.md	specs/standards/{domain}/
docs/security-standards.md	specs/standards/security/security.spec.md
docs/coderabbit-derived-conventions.md	specs/standards/platform/cross-cutting.spec.md
.claude/skills/*	.agents/skills/ (with domain nesting)

What Stayed

• .specify/ — out of scope (SDD tooling)
• .claude/plugins/ — distinct from skills
• docs/internal/ non-spec/guide files — docs website content
• docs/superpowers/ — docs website content
• Numbered spec directories (specs/001-*/, etc.) — kept, ephemeral artifacts removed

New Skills

• /discover — mandatory first step for all coding/spec work; discovers domain-specific skills and context
• /spec — guides spec creation following the format and 8-phase spec-change workflow

New Workflows

• spec-change.workflow.md — 8-phase process: frame, ground in codebase, draft, critic pass, synthesize, design questions, apply fixes, second critic pass

Symlink Design

Claude Code requires flat skill discovery. Domain-specific skills are nested under .agents/skills/{domain}/ but discoverable via symlinks:

• .claude/skills -> ../.agents/skills — top-level cross-cutting skills
• specs/{domain}/.agents/skills -> ../../../.agents/skills/{domain} — domain storage
• specs/{domain}/.claude/skills -> ../.agents/skills — domain Claude Code discovery

Resolved Questions

1. Standards location — specs/standards/{domain}/ with technology-aligned domains (backend, frontend, control-plane, security, platform)
2. Implementation guides — renamed to *.workflow.md and moved to .agents/workflows/
3. Ephemeral artifacts — deleted (plan.md, tasks.md, research.md, etc.)