swe-workflow-skills 0.6.2 → 0.6.3

package/VERSION

@@ -1 +1 @@
-0.6.2
+0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {

package/skills/architecture-design/SKILL.md

@@ -10,6 +10,36 @@ Help the user make well-reasoned architectural decisions and document them in Ar
 
 ## Workflow
 
+### Step 0: Inventory What Already Exists
+
+If a system is already running, establish what it already provides before
+proposing a new service, module, boundary, or pattern. Map the current state
+**directly** from the codebase — don't infer it from the requirements, the docs,
+or memory. Docs describe the system someone intended; the code is the one you
+have.
+
+Cover both:
+
+- **Artifacts** — existing services, modules, and seams that already own, or
+  could own, the responsibility in question. Search by capability, not just by
+  name: the component that does this may be called something else entirely.
+- **Written decisions** — the ADR log, established conventions, and prior audit
+  findings. A decision already made and recorded is not yours to re-litigate
+  silently; supersede it explicitly or work within it.
+
+**Exit condition** — one line, then keep going in the same response:
+*"`<existing component>` already handles `<responsibility>`; it does / does not
+serve this because `<reason>`."*
+
+**This step is not a gate on delivering.** Greenfield — nothing built yet, or
+nothing you can reach — closes it in one line: say so and go straight to Step 1.
+When you can't inspect, name what you would check and continue under stated
+assumptions. Never answer a design question with inventory and questions alone;
+carry the options, the recommendation, and the trade-offs in the same reply.
+
+This constrains the input, not the choice. A new component is a fine outcome;
+an unexamined one isn't.
+
 ### Step 1: Frame the Decision
 
 Identify the exact decision to be made. A good architectural question is specific and scoped:
@@ -26,7 +56,8 @@ If the user's question is too broad, help narrow it by asking:
 
 Understand the current state before proposing changes:
 
-- **Current architecture**: What exists today? Read the codebase if available.
+- **Current architecture**: the Step 0 finding — what exists today, established
+  from the code rather than assumed. If you can't state it, Step 0 isn't done.
 - **Quality attributes that matter**: Performance? Scalability? Developer experience? Maintainability? Deployment simplicity?
 - **Team context**: Team size, expertise, on-call burden
 - **Growth trajectory**: Expected scale in 6-12 months (not 5 years — YAGNI)

package/skills/configuration-strategy/SKILL.md

@@ -8,6 +8,33 @@ allowed-tools: Read, Grep, Glob, Write, Edit
 
 Design configuration that is safe, auditable, and easy to change. Most configuration problems (hardcoded secrets, production config in dev, feature flags with no off-switch) come from not designing the system upfront.
 
+## Step 0: Inventory What Already Exists
+
+Before introducing a new environment variable, secret, feature flag, or
+constant, establish what the project already defines. Inspect the current state
+**directly** — grep the tree; don't infer it from the requirements or memory.
+
+Cover both:
+
+- **Artifacts** — existing key names *and* the values themselves. Search for the
+  literal value, not just the name: the same timeout or limit is often already
+  hardcoded in two places, and adding a third is the common failure.
+- **Written decisions** — config conventions, naming schemes, `.env.example`,
+  and prior audit findings that already govern where things live.
+
+**Exit condition** — one line, then keep going in the same response:
+*"`<existing key>` already carries `<value>`; it does / does not serve this
+because `<reason>`."*
+
+**This step is not a gate on delivering.** Greenfield — nothing configured yet,
+or nothing you can reach — closes it in one line: say so and go straight to
+Step 1. When you can't inspect, name what you would check and continue under
+stated assumptions. Never answer with inventory and questions alone; produce the
+configuration design in the same reply.
+
+This constrains the input, not the choice. A new key is a fine outcome; an
+unexamined one isn't — and a duplicated value will drift.
+
 ## Step 1: Identify All Configuration Needed
 
 List every piece of configuration the feature or service requires:

package/skills/data-modeling/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: data-modeling
 description: "Design database schemas, relationships, indexes, and migration strategies — relational and document stores. Triggers: data model, schema design, ER diagram, database schema, table design, foreign key, index strategy, normalization, denormalization, migration plan, document model, partition key."
-allowed-tools: Read, Grep, Glob, Write, Edit
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
 ---
 
 # Data Modeling
@@ -10,6 +10,36 @@ Guide the user through designing data models that are normalized, consistent, an
 
 ## Workflow
 
+### Step 0: Inventory What Already Exists
+
+If any database exists, establish what it already holds before proposing a
+single new table, column, or index. Inspect the current schema **directly** —
+don't infer it from the requirements, the ORM models, or memory. Dump it from
+the live database where you can reach one, otherwise read the migration history
+end to end.
+
+Cover both:
+
+- **Artifacts** — existing tables, columns, and indexes that hold, or could
+  hold, the fact in question. Grep for the concept by name and by synonym; the
+  right table is often named for a different concern than the one you're serving.
+- **Written decisions** — ADRs, schema conventions, and prior audit findings
+  that already constrain the shape.
+
+**Exit condition** — one line, then keep going in the same response:
+*"`<existing table>` already stores `<fact>`; it does / does not serve this
+because `<reason>`."*
+
+**This step is not a gate on delivering.** Greenfield — no database yet, or none
+you can reach — closes it in one line: say so and go straight to Step 1. When
+you can't inspect (no repo access, a conversational answer), name what you would
+check and continue under stated assumptions. Never answer a schema request with
+inventory and questions alone; produce the model in the same reply.
+
+This constrains the input, not the choice. A new table is a fine outcome; an
+unexamined one isn't — and a second home for the same fact is duplication
+however well it's named.
+
 ### Step 1: Understand the Domain
 
 Before touching schemas, understand the business domain:

package/skills/frontend-architecture/SKILL.md

@@ -14,6 +14,35 @@ Design the technical structure of frontend applications — component hierarchy,
 
 ## Workflow
 
+### Step 0: Inventory What Already Exists
+
+In an existing codebase, establish what the app already provides before adding a
+new component, hook, store, or token. Search the shared surfaces **directly** —
+`components/`, `hooks/`, `lib/`, the token file, and each feature's public
+`index.ts` — rather than inferring from the design or from memory.
+
+Cover both:
+
+- **Artifacts** — existing components, hooks, stores, and tokens that already
+  cover, or nearly cover, the need. Search by behavior, not just by name: the
+  component you want often exists under a different label.
+- **Written decisions** — established conventions, the design system's rules,
+  and prior audit findings.
+
+**Exit condition** — one line, then keep going in the same response:
+*"`<existing component/hook>` already covers `<behavior>`; it does / does not
+serve this because `<reason>`."*
+
+**This step is not a gate on delivering.** Greenfield — a new app, or a codebase
+you can't reach — closes it in one line: say so and go straight to Step 1. When
+you can't inspect, name what you would check and continue under stated
+assumptions. Never answer with inventory and questions alone; produce the
+architecture in the same reply.
+
+This constrains the input, not the choice. A new component is a fine outcome; an
+unexamined one isn't — a near-duplicate of an existing one is how design systems
+rot.
+
 ### Step 1: Design the Component Hierarchy
 
 Start from the UI design (or the screen spec from `ui-ux-design`) and decompose into components:

package/skills/plan-execution/SKILL.md

@@ -80,6 +80,14 @@ when any of these fires:
 - two consecutive checkpoints failed verification
 - you catch yourself thinking "the plan didn't anticipate this, but I'll just…"
 
+A **structural question the plan didn't answer** fires this too: where a piece
+of state lives, whether to add a table, column, service, module, store, or
+config key. Don't settle it inline — **invoke `data-modeling` (data shape) or
+`architecture-design` (structure and boundaries)** and let it run its inventory
+of what already exists. These decisions arrive disguised as implementation
+details, and they're the ones the plan is least able to absorb silently:
+persistent constructs outlive the plan that introduced them.
+
 Re-planning openly is cheap; silently executing a plan that no longer matches
 reality delivers the wrong thing with perfect discipline. Sunk progress is not a
 reason to continue — the remaining work costs the same whether or not you admit
@@ -109,6 +117,7 @@ that still describes the pre-drift design is a stale document like any other.
 | "The docs can come after the plan lands" | The plan changed what the docs describe; landing it leaves them actively wrong, and nobody re-derives the whole surface later. Reconcile at close-out. |
 | "I already have the Iron Law in context, invoking the gate is redundant" | Quoting a law isn't running the gate. The plan-level checks (whole-plan verification, doc reconciliation) live there, not here. |
 | "The plan is outdated here; I'll adapt as I go" | That's drift. Log it; if it's structural, stop and re-plan — don't decide alone silently. |
+| "This is an implementation detail, not an architecture decision" | Anything that persists — a table, a column, a config key, a shared module — is structure, whatever task it arrived under. Route it to the design skill. |
 | "We're 80% through; re-planning now wastes all that work" | Sunk cost. Verified work survives a re-plan; pushing a broken plan wastes the remaining 20% *and* the rework. |
 | "Marking them done unblocks the team; we'll backfill verification" | A false "done" misinforms every decision downstream. Report the honest state instead. |
 
@@ -118,11 +127,15 @@ that still describes the pre-drift design is a stale document like any other.
 - You can't say what command verified the last checkpoint.
 - "Should work" / "looks done" appearing in your status report.
 - Mid-execution, you're building something the plan never mentioned.
+- You're about to add a persistent construct (table, column, config key, shared
+  module) that the plan never named — and you haven't checked what already exists.
 - You've stopped consulting the plan and are working from memory.
 
 ## Cross-Skill References
 
 - `feature-planning` — creates and (on re-plan) revises the plan this skill executes
+- `data-modeling` — where a schema question surfaced mid-execution belongs
+- `architecture-design` — where a structural or boundary question belongs
 - `verification-before-completion` — the per-claim evidence gate each checkpoint applies
 - `tdd-workflow` — how the implementation tasks inside a batch get built
 - `git-workflow` — commit at checkpoint boundaries; the evidence belongs in the message

package/skills/writing-skills/SKILL.md

@@ -104,7 +104,10 @@ As base models improve, a skill can become pure overhead. Once per release cycle
 — or on a major base-model update — re-run the skill's 3 evals RED on shipping
 models via `evals/workflow-runner.mjs`; re-sample ×3 on borderline scores and
 read the judge journal before calling a result variance (a "flaky" case is often
-a real content gap the skill causes). If RED ≈ GREEN across all 3 evals (0/0
+a real content gap the skill causes). **First check the skill's reference mass:**
+the harnesses can't read `references/` or `templates/`, so where that content
+rivals `SKILL.md` the RED ≈ GREEN verdict is a harness artifact — judge those by
+hand instead. Otherwise, if RED ≈ GREEN across all 3 evals (0/0
 tool-dependent assertion pairs don't count), **slim first** — cut what the model
 does unaided; keep the Iron Law, boundaries, and cross-skill references — then
 re-run GREEN (gate: GREEN ≥ RED per case). Retire only after a slimmed skill