solid-coder

solid-coder

A Claude Code plugin for spec-driven implementation, principle-based review, and structured self-correction.

solid-coder is not a single prompt loop. It is a staged workflow system built around:

• spec creation and validation
• code-aware planning
• reuse / modify / create decisions
• rule-aware coding
• structured principle review
• safe correction routed back through code

The most important idea is that rules are applied before code is written, and again after code is written.

---

Core workflows

build-spec

Interactive spec authoring for new or evolving work.

build-spec-from-code

Generate a rewrite-oriented spec from existing code.

implement

Run the staged spec-to-code pipeline:

1. plan
2. validate-plan
3. synthesize-implementation
4. code
5. refactor

refactor

Run principle-based review and structured correction for changed code.

---

Workflow overview

flowchart TD
    A[build-spec] --> VS[validate-spec]
    B[build-spec-from-code] --> VS
    VS --> I[implement]
    I --> P[plan]
    P --> VP[validate-plan]
    VP --> SI[synthesize-implementation]
    SI --> C[code]
    C --> R[refactor]

---

Implement flow

flowchart TD
    S[validated spec] --> P[plan]
    P --> VP[validate-plan]
    VP --> SI[synthesize-implementation]
    SI --> D{per component}
    D -->|reuse| RU[reuse existing code]
    D -->|modify| MO[modify existing code]
    D -->|create| CR[create new code]
    RU --> C[code]
    MO --> C
    CR --> C
    C --> R[refactor]

---

Refactor flow

flowchart TD
    A[changed files] --> PRI[prepare-review-input]
    PRI --> DP[discover-principles]
    DP --> APR[apply-principle-review]
    APR --> VF[validate-findings]
    VF --> SF[synthesize-fixes]
    SF --> C[code]

---

Rule discovery and application

The rule system has three layers:

1. Principle discovery
2. Rule / instruction front matter parsing
3. Contextual loading inside code and refactor

High-level rule pipeline

flowchart TD
    RP[references/*/rule.md] --> D[discover-principles]
    D --> CT[all_candidate_tags]
    CT --> PRI[prepare-review-input]
    PRI --> MT[matched_tags]
    MT --> D2[discover-principles filtered]
    D2 --> AP[active principles]

    AP --> PF[parse-frontmatter]
    PF --> FL[files_to_load]

    AP --> CODE[code]
    AP --> APR[apply-principle-review]

    FL --> LR[load-reference]
    LR --> CODE
    LR --> APR

What discover-principles does

discover-principles scans references/*/rule.md, parses each rule front matter, and returns:

• active_principles
• skipped_principles
• all_candidate_tags

Rule tags come from each rule.md front matter.

Important behavior:

• untagged rules are always active
• if no filtering input is provided, all rules are returned as active
• if matched_tags are provided, only tagged rules with intersecting tags remain active

This means:

• core rules can always apply
• framework or stack-specific rules activate only when code evidence matches them

---

How tags are matched

prepare-review-input receives candidate_tags from the orchestrator and matches them against the code being reviewed.

It uses:

• detected_imports
• direct code-pattern inspection
• semantic matching for tags that are not simple import names

Examples:

• swiftui can match import SwiftUI
• gcd can match DispatchQueue
• structured-concurrency can match async, await, or Task {
• combine can match Publisher or Subscriber

The result is written into review-input.json as matched_tags.

That file is then fed back into discover-principles to narrow the principle set.

---

Rule front matter vs code front matter

These are different and serve different purposes.

Rule front matter

Every principle folder has a rule.md with front matter such as:

• name
• displayName
• category
• description
• tags
• examples

This front matter is used to:

• identify the principle
• expose candidate tags
• locate examples and referenced files to load

Code front matter

Generated top-level types can receive semantic comments such as:

• solid-name
• solid-category
• solid-stack
• solid-description

This front matter is used to:

• describe the type's role
• improve later discovery in validate-plan
• help expose stack or framework context in the codebase

Example:

/**
 solid-name: DSTheme
 solid-category: design-system theme facade
 solid-stack: swiftui
 solid-description: resolves design tokens for color, spacing, typography, elevation, and motion.
 */

solid-stack matters because it can help make framework usage more explicit in the codebase, but it is not the only signal used for rule activation. Imports and actual code patterns are also part of the discovery story.

---

How code applies rules