agentsclimarketplace

Plan

Skill alfredoperez/sdd/skills/plan

SDD — Spec-Driven Development: write a lean implementation plan.From its SKILL.md

Install
npx -y skills add alfredoperez/sdd --skill plan

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

11.2 KB, as published. Nobody here has run it

Shared Instructions

  • Transition Logging — append a transition entry on every .spec-context.json write
  • Hook Execution — run user-configured hooks at supported pipeline points
  • Layered Context — load Layer 1 living specs by domain (Step 1) and grade alignment (Step 2b)

Steps

1. Load Context

If $ARGUMENTS is provided, use specs/{$ARGUMENTS}/ as the target directory. Otherwise, find the most recently modified directory under specs/ that contains a spec.md.

Read in parallel:

  • specs/{NNN}-{slug}/spec.md — feature name, requirements, scenarios
  • specs/{NNN}-{slug}/.spec-context.json — current step/task (if exists)
  • .sdd/principles.md — Layer 0 of the layered context model. Optional. If the file exists at the project root, load it; the bullet list of MUSTs will be checked against the Approach in Step 2 (Principles Check). If absent, skip the check entirely — principles.md is opt-in by presence.
  • Layer 1 (Living specs). Per layered-context: if loadedDomains is already in .spec-context.json (set by /sdd:specify Step 3b), read each domain's .spec.md at its resolved path. Otherwise run python3 lib/scripts/resolve-spec-paths.py --changed <Files-to-Change> (or files referenced in the Summary) and persist the matched names to loadedDomains. Read in returned order (most-specific first). Empty list → skip Layer 1 silently.

If no spec found, stop: "Run /sdd:specify first."

Update specs/{NNN}-{slug}/.spec-context.json and append a transition entry per transition-logging:

{ "currentStep": "plan", "currentTask": null, "progress": "loading", "next": "tasks", "updated": "{TODAY}" }

Run pre:plan hooks per hook-execution with vars = { slug, spec-dir }.


2. Write specs/{NNN}-{slug}/plan.md

Update specs/{NNN}-{slug}/.spec-context.json — set progress to "writing-plan" and append a transition entry per transition-logging.

Read lib/templates/plan.md, fill placeholders ({Feature Name}, {NNN}, {slug}, {TODAY}), include or omit optional sections (Technical Context, Flow, Data Model, Risks) based on feature complexity, and write to specs/{NNN}-{slug}/plan.md. Technical Context (Key Dependencies / Constraints) is project-fixed — omit the section entirely unless this spec changes language, runtime, or test framework.

Skip: research.md, contracts/, quickstart.md, auxiliary work flags. Optional (include when relevant): Technical Context, Data Model table, Mermaid flow diagram, Principles Check (see 2a below).

2a. Principles Check (only if .sdd/principles.md was loaded in Step 1)

After the Approach section is drafted, scan the Approach text against each principle bullet from .sdd/principles.md. The check is soft-warning only — never blocks the pipeline.

For each principle, ask: does the Approach contain wording that contradicts this principle?

  • Match on intent, not exact strings (e.g., principle "All UI strings must go through i18n" → flag if Approach says "hardcode the dialog text")
  • Skip principles that don't apply to this feature's domain (e.g., a backend change need not be checked against a UI accessibility principle)

If any conflicts found, append this section to plan.md (after Approach, before Files):

## ⚠ Principles Check

- **<principle one-line summary>** — <how the Approach conflicts; one line>
- **<principle one-line summary>** — <how the Approach conflicts; one line>

> Soft warning. The plan can proceed; address before implement or acknowledge in CP1.

If no conflicts found, omit the section entirely (per template convention — never leave empty sections).

Record the count: set step_summaries.plan.principles_concerns to the integer count (0 if none, or if no .sdd/principles.md was loaded). This is read in Step 3 to surface the count in the footer.

2b. Domain Alignment Check (only if Layer 1 specs were loaded in Step 1)

For each loaded domain's living spec (at resolve(<domain>), per layered-context "Living-spec path resolution"), scan its ## Requirements section against the Approach + Files-to-Change in plan.md. The check is soft-warning only — never blocks the pipeline. Same shape as 2a (Principles Check).

For each domain, ask:

  • Does the Approach contradict an existing requirement in this domain (e.g., domain says "passwords must be hashed with Argon2id" but Approach proposes bcrypt)?
  • Does the Approach silently expand the domain's surface (introduces a new capability without an ## ADDED Requirements block in spec.md)?
  • Does the Approach modify a requirement without a ## MODIFIED Requirements block in spec.md?

If any conflicts found, append this section to plan.md (after Approach + Principles Check, before Files):

## ⚠ Domain Alignment

- **{domain}** — <one-line description of the conflict; suggest the delta block to add>
- **{domain}** — <…>

> Soft warning. Add the matching delta block(s) to `specs/{NNN}-{slug}/spec.md` before implement so CP3 can sync them into Layer 1.

If no conflicts, omit the section entirely.

Record the count: set step_summaries.plan.domain_concerns to the integer count (0 if none, or if no Layer 1 specs were loaded). Surfaced in the Step 3 footer.

2c. Decision Significance Heuristic

After 2a and 2b have written their sections, score the Approach to decide whether this plan deserves a dedicated ADR (Architectural Decision Record).

Signals (count how many fire):

  1. Multiple alternatives weighed. The Approach (or a "Considered" / "Alternatives" subsection) explicitly compares ≥3 candidate solutions or libraries.
  2. Cross-domain reach. loadedDomains from Step 1 has 2+ entries, OR the plan's Files table touches files matching 2+ distinct top-level source directories.
  3. New external dependency. The Approach mentions adopting a new package, vendor, runtime, protocol, or persistence engine the project does not already use (e.g., "introduce Redis", "add Stripe SDK", "switch to Postgres").

Action:

  • Score < 2 → silent; continue to Step 3.
  • Score ≥ 2 → use AskUserQuestion with the prompt This plan looks architecturally significant ({signal-summary}). Draft an ADR to capture the decision? and options Yes, No, Skip.
    • Yes → derive <adr-slug> from the spec slug (drop leading add-/fix- if present, kebab-case, max 4 words) and invoke /sdd:adr <adr-slug> via the Skill tool. The ADR is scaffolded as Status: Proposed — the user fills it in. Record step_summaries.plan.adr_drafted: "<NNNN>-<adr-slug>" in .spec-context.json.
    • No → continue. Record step_summaries.plan.adr_drafted: false.
    • Skip → continue silently. Do not set the field.

If .sdd/decisions/ does not exist (i.e., the user has not run /sdd:init), skip the prompt entirely — there is nowhere to write the ADR. Record nothing.

Record the score: set step_summaries.plan.significance_score to the integer (0–3). Used by future tooling; does not surface in the Step 3 footer.

Run post:plan hooks per hook-execution with vars = { slug, spec-dir }.


3. Summary

Update specs/{NNN}-{slug}/.spec-context.json — set progress to null, next to "tasks", and include approach and step_summaries.plan. Append a transition entry per transition-logging:

{
  "currentStep": "plan",
  "currentTask": null,
  "progress": null,
  "next": "tasks",
  "updated": "{TODAY}",
  "approach": "one-line summary from the plan's Approach section",
  "step_summaries": {
    "specify": { "..." : "preserve existing step_summaries.specify if present" },
    "plan": {
      "approach_summary": "one-line summary from the plan's Approach section",
      "files_planned": N,
      "risks": ["risk string 1", "risk string 2"]
    }
  }
}

Where:

  • approach: one-line summary extracted from the first sentence of the plan's ## Approach section
  • step_summaries.plan.approach_summary: same as approach
  • step_summaries.plan.files_planned: total count of files in the Create + Modify tables in plan.md
  • step_summaries.plan.risks: array of risk strings from the ## Risks section; empty array [] if no risks
  • step_summaries.plan.principles_concerns: integer count from Step 2a Principles Check (0 if no concerns, or if .sdd/principles.md was not loaded)
  • step_summaries.plan.domain_concerns: integer count from Step 2b Domain Alignment Check (0 if no concerns, or if no Layer 1 specs were loaded)
  • step_summaries.plan.significance_score: integer 0–3 from Step 2c Decision Significance Heuristic
  • step_summaries.plan.adr_drafted: "<NNNN>-<slug>" if Step 2c drafted an ADR, false if user declined, omitted if Step 2c did not prompt or user chose Skip
  • Preserve any existing step_summaries.specify from the specify step

Read auto from specs/{NNN}-{slug}/.spec-context.json. If auto is true, use the (auto) variant. Otherwise use the (manual) variant.

Manual — display exactly this format:

📐 **Plan ready**

{Feature Name} — {1-line summary of approach from plan's Approach section}
{N} files to create · {N} to modify
{principles-line}
{domain-line}

📂 `specs/{NNN}-{slug}/plan.md`

👉 Run `/sdd:tasks {NNN}-{slug}` to break it into tasks

Auto — display exactly this format:

📐 **Plan ready**

{Feature Name} — {1-line summary of approach from plan's Approach section}
{N} files to create · {N} to modify
{principles-line}
{domain-line}

📂 `specs/{NNN}-{slug}/plan.md`

🔄 Auto mode — continuing...

{principles-line} rules:

  • If .sdd/principles.md was not loaded in Step 1: omit the line entirely.
  • If loaded with 0 concerns: ✓ Principles check passed
  • If loaded with N concerns (N > 0): ⚠ {N} principles concern{s} — see plan.md § Principles Check

{domain-line} rules:

  • If no Layer 1 specs were loaded in Step 1: omit the line entirely.
  • If loaded with 0 concerns: ✓ Aligned with {domain} (or ✓ Aligned with {N} domains if multiple)
  • If loaded with N concerns (N > 0): ⚠ {N} domain concern{s} — see plan.md § Domain Alignment

4. Auto Self-Chain

Only runs when auto is true. Skip entirely in manual mode.

After displaying the Auto summary above, invoke /sdd:resume {NNN}-{slug} via the Skill tool. This makes the "continuing..." footer real when /sdd:plan is invoked directly (outside the /sdd:auto orchestrator loop) on a spec that has auto: true.

Safe under nesting: when /sdd:auto invokes /sdd:plan, this self-chain fires first and advances to /sdd:tasks; when control returns to /sdd:auto's loop, /sdd:resume is idempotent — it reads currentStep from .spec-context.json and resumes or no-ops as appropriate.

Keep looking

Skills are one crate of 609,689. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.