Skip to content

CLAUDE.md

Latest commit

 

History

History
62 lines (41 loc) · 4.95 KB

CLAUDE.md

File metadata and controls

62 lines (41 loc) · 4.95 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository is

This is a Claude Code plugin, not an application. It contains no runtime code, build system, or test suite — the "source" is a set of Markdown skill definitions bundled into a plugin. The plugin (agentic-support-workflow) packages the spec-driven development workflow skills used across Open Elements projects, extracted from claude-base.

When you edit this repo you are authoring prompts/instructions for future Claude Code sessions, not writing executable code. Treat each SKILL.md as a prompt whose quality is judged by whether another Claude instance can follow it unambiguously.

Validate

There is no build or test command. The one check is plugin validation:

claude plugin validate ./ --strict

Layout

  • .claude-plugin/plugin.json — plugin manifest (name, version, metadata)
  • .claude-plugin/marketplace.json — self-contained open-elements marketplace catalog listing this plugin (source: "./")
  • skills/<name>/SKILL.md — one skill per directory; the frontmatter description is what Claude matches a user request against, so it must precisely enumerate trigger phrases and when-to-use conditions
  • skills/_workflow-shared/spec-driven-development.md — shared reference read by the spec skills; defines the canonical docs/specs/ structure, INDEX.md format, Drift Log, and TODO backlog conventions
  • conventions/software-quality.md, conventions/security.md — convention documents that quality-review and project-quality-audit read and enforce against target projects

Note: skills reference the shared doc with a relative path (../_workflow-shared/spec-driven-development.md) and reference each other by slash command (e.g. /spec-implement). Preserve both when moving or renaming files.

How the skills relate (the big picture)

These skills are not independent tools — they form a spec-driven pipeline where each stage produces durable Markdown under a target project's docs/ that the next stage consumes:

/vision → docs/vision.md
   → /proposal-create → docs/proposals/<id>-<slug>.md   (non-technical stakeholder, plain language)
      → /spec-create → docs/specs/<id>-<slug>/{design.md, behaviors.md}   (engineer, technical)
         → /spec-implement → steps.md
            → /spec-flow (orchestrates: issue → branch → implement → spec-review + quality-review loop → PR)

/proposal-create is the non-technical rung: a stakeholder describes what they want in business language and every technical decision is parked under Open questions for engineering rather than answered. /spec-create then consumes the proposal, resolves those questions with an engineer, and freezes the proposal as an input record (status promoted).

Key invariants that hold across skills (defined in _workflow-shared/spec-driven-development.md):

  • docs/specs/INDEX.md is the source of truth for which specs exist and their status (open / in progress / done). Any skill that creates or advances a spec updates this index.
  • A done spec is frozen — design.md and behaviors.md are historical records. Later divergence is not edited into them; it is appended as a Drift Log section, and only /spec-review writes those entries.
  • design.md always starts with a self-contained ## Summary so an agent can head the file to decide relevance without loading the whole thing.
  • behaviors.md uses given-when-then scenarios that map 1:1 to tests — /spec-review verifies every scenario has a corresponding test.
  • All spec documents are written in English, regardless of the conversation language.
  • /roadmap-execute runs the whole pipeline autonomously over a docs/roadmap.md, delegating each step to a fresh sub-agent to keep the orchestrator's context lean.
  • /grill-me is a dependency of /vision and /adr-create, which invoke it to stress-test thinking before writing.

The quality skills enforce Open Elements thresholds against target projects: backend ≥80% / frontend ≥70% test coverage, reproducible builds, and the rules in conventions/.

Authoring conventions for skills

  • Frontmatter must include name, license: Apache-2.0, metadata (source, author), and a description. The description is load-bearing for skill matching — write it as an exhaustive trigger list, following the style of the existing skills.
  • Keep the pipeline vocabulary consistent (design.md, behaviors.md, steps.md, INDEX.md, Drift Log, TODO backlog). Skills cross-reference these by exact name.

Releasing

Bump version in both .claude-plugin/plugin.json and the plugin's entry in .claude-plugin/marketplace.json (they must match), add a CHANGELOG.md entry, tag the release, and run claude plugin validate ./ --strict. Users only receive an update when the version is bumped.